@sema-agent/server 7.5.0 → 7.7.0

package/dist/capabilities/scenarios.js

@@ -7,6 +7,7 @@ import { stablePrompt } from "./prompt.js";
 import { createTeamTool, teamCoordinatorPrompt, getTeam, teamNames } from "./team.js";
 import { createWebSearchBackend, webSearchConfigFromSettings } from "../plugins/web-search.js";
 import { skillsForScenario } from "./skills.js";
+import { pickHandsRunner } from "./hands-lane.js";
 /**
  * Sema product identity, prepended to the core default base for the `default` scenario when
  * {@link ScenarioDeps.brandIdentity} is on. Honest about the substrate (the engine runs whichever model
@@ -88,6 +89,11 @@ export function codePromptProvider(brand) {
 // [2400] CAPS-OPS-11:autonomousPromptProvider 别名导出已随场景退役删除(真身=codePromptProvider)。
 // 其 `@deprecated` JSDoc 曾残留于此,被 tsc 误挂到下方 buildScenarios(三处调用点全告 deprecated
 // ——TODO-3 立案的「迁移」实为孤儿注释,随删除清账;buildScenarios 本身非退役面)。
+/** #196 唯一取用口:场景按自己的判别位取子任务 Runner。场景体内一律不直接摸 `deps.subRunner` /
+ *  `deps.handslessSubRunner` —— 两处各挑一次就是漂移的成因,判别位必须是唯一开关。 */
+function subRunnerFor(deps, hands) {
+    return pickHandsRunner(hands, { full: deps.subRunner, handsless: deps.handslessSubRunner });
+}
 export function buildScenarios(deps) {
     // The default scenario filters skills by "default" — NOT by req.scenario (which may be an unknown name
     // that fell back here): the bundle must be a coherent "default" set, matching how main.ts resolves an
@@ -137,7 +143,9 @@ export function buildScenarios(deps) {
                     // core 1.382 checkpointStore/ensureChildSessionDurable = design/153 parked 状态机的「同车必接」
                     // 一对([1561] 提货单①②,ScenarioDeps 字段注释详述);两者任一缺席 = 净是 pre-153 行为。
                     subagent: {
-                        runner: deps.subRunner,
+                        // #196:default/code 的委派子代**要**手(CC parity;main.ts subRunner 注里那条 "subagent
+                        // couldn't run pwd" 缺陷就是这条腿缺手),故按本场景判别位取 full 支。
+                        runner: subRunnerFor(deps, "full"),
                         background: {
                             registry: defaultTaskRegistry,
                             owner: "unattributed",
@@ -158,6 +166,9 @@ export function buildScenarios(deps) {
                     ...(webSearch ? { webSearch } : {}),
                 }).filter((t) => t.name !== "WebFetch" || deps.requirePrincipal !== true),
             ],
+            // default/code 是手带并集的**故意消费者**(上方 rank-1 BLOCKER 注:CC agent loop MUST have the
+            // full-body roster)——#196 判别位在这里表态 full,收窄只落在声明了 none 的场景上。
+            hands: "full",
             skills: skillsForScenario(deps.skills, "default"),
             // Local/TOC deployment brands the neutral default scenario as Sema (so the local engine answers "who
             // are you" as Sema, not the model's hallucinated identity). Cloud leaves it neutral unless opted in.
@@ -190,13 +201,15 @@ export function buildScenarios(deps) {
         // would let runtime-distributed content rewrite the deployment-pinned system prompt and break the
         // stablePrompt STABLE→VARIABLE prefix-cache discipline (design/12/17).
         scan: (req) => {
-            if (!deps.repoClient)
-                throw new HttpError(501, "scan scenario needs GIT_API_BASEURL configured");
+            const repoClient = requireRepoClient(deps, "scan");
             if (typeof req.repo !== "string" || !req.repo.trim()) {
                 throw new HttpError(400, "scan scenario requires a 'repo' field (owner/name or repo URL)");
             }
             return {
-                tools: [...repoToolsFor(deps.repoClient, parseRepo(req.repo)), nowTool()],
+                tools: [...repoToolsFor(repoClient, parseRepo(req.repo)), nowTool()],
+                // #196:头注的「工具集即边界」自此在**最终 roster** 上成立(修前 core 把手带 band 并集进来,
+                // clone-free 承诺只存在于这份声明里)。
+                hands: "none",
                 skills: skillsForScenario(deps.skills, "scan"),
             };
         },
@@ -212,8 +225,11 @@ export function buildScenarios(deps) {
             }
             const objective = typeof req.objective === "string" ? req.objective : "Discuss the task.";
             const businessContext = typeof req.businessContext === "string" ? req.businessContext : undefined;
+            // #196:成员/synthesizer 是纯讨论人格(模板声明零工具),跑在无手 subRunner 上。
+            const hands = "none";
             return {
-                tools: [createTeamTool(deps.subRunner, template, { objective, businessContext })],
+                tools: [createTeamTool(subRunnerFor(deps, hands), template, { objective, businessContext })],
+                hands,
                 skills: skillsForScenario(deps.skills, "team"),
                 promptProvider: teamCoordinatorPrompt,
             };
@@ -224,6 +240,11 @@ export function buildScenarios(deps) {
 export function selectScenario(scenarios, name) {
     return (name && scenarios[name]) || scenarios.default;
 }
+/** 把属主的判别式摊平成 wire 上的两个键(可用臂整键省略原因,契约=「缺席即没有理由」)。 */
+function availabilityFields(deps, toolset) {
+    const verdict = scenarioAvailability(deps, toolset);
+    return verdict.available ? { available: true } : { available: false, unavailableReason: verdict.reason };
+}
 /** 内建五场景详情。default/code/team 工厂对良性请求无副作用可真调(拿真实工具名单);code-review/scan 是
  *  fail-loud 语义(缺 GIT_API 配置/principal 即 throw)→ 探针失败落静态表兜底(表↔工厂一致性由测试锁:
  *  测试喂 fake deps 真调工厂对账工具名)。enabled 对内建恒 true(约定②)。 */
@@ -237,7 +258,12 @@ export function builtinScenarioDetails(scenarios, deps) {
         }
     };
     const REPO_TOOLS = ["repo_tree", "repo_read_file", "repo_pull_diff", "Now"];
-    const mk = (name, summary, toolset, tools, promptSummary) => ({ name, source: "builtin", builtin: true, summary, toolset, tools, promptSummary, enabled: true });
+    const mk = (name, summary, toolset, tools, promptSummary) => ({
+        name, source: "builtin", builtin: true, summary, toolset, tools, promptSummary, enabled: true,
+        // [C132]:可用性与上面的静态回退表分家 —— 回退表答的是「工具面长什么样」(缺配置时也照画),
+        // 这两个键答的是「现在点下去会不会 501」。同一份属主判据,内建与 center 两条产线共用。
+        ...availabilityFields(deps, toolset),
+    });
     return {
         code: mk("code", "编码主场景([891] 出厂缺省;CC 编码 persona 蒸馏版,default 全量工具面;终验旋钮独立)", "full-body", probe("code", {}, undefined, ["Now"]), deps.brandIdentity
             ? "Sema 产品身份 + core 编码完全体提示词(CODE_AGENT persona+自治自检;CC 血统对表)"
@@ -250,7 +276,7 @@ export function builtinScenarioDetails(scenarios, deps) {
 }
 /** center 条目详情(有效性判定与 centerScenarios 完全同款:无效条目既不进 overlay 也不进详情——
  *  保证约定①「详情显示的来源=运行实际用的定义」永不错位)。 */
-export function centerScenarioDetails(specs, builtinNames) {
+export function centerScenarioDetails(specs, builtinNames, deps) {
     const out = {};
     for (const spec of specs ?? []) {
         if (spec.enabled === false)
@@ -270,24 +296,62 @@ export function centerScenarioDetails(specs, builtinNames) {
             // 恒空串;字段本身保留(builtin 条目仍有真值,wire 形不变)。
             promptSummary: "",
             enabled: true,
+            // [C132]:center 声明的 repo 型场景与内建的 scan/code-review 受**同一份**判据管辖
+            // ——overlay 不是判据的第二属主。
+            ...availabilityFields(deps, spec.toolset),
         };
     }
     return out;
 }
 const TOOLSETS = {
-    none: { build: () => [nowTool()] },
+    none: { build: () => [nowTool()], hands: "none" },
     "repo-readonly": {
         requiresRepo: true,
+        hands: "none",
         build: (deps, req) => {
-            if (!deps.repoClient)
-                throw new HttpError(501, "this scenario needs GIT_API_BASEURL configured");
+            const repoClient = requireRepoClient(deps, "this");
             if (typeof req.repo !== "string" || !req.repo.trim()) {
                 throw new HttpError(400, "this scenario requires a 'repo' field (owner/name or repo URL)");
             }
-            return [...repoToolsFor(deps.repoClient, parseRepo(req.repo)), nowTool()];
+            return [...repoToolsFor(repoClient, parseRepo(req.repo)), nowTool()];
         },
     },
 };
+const SCENARIO_AVAILABLE = { available: true };
+/**
+ * 🔴 场景可用性的**唯一属主**。列举面(`ScenarioDetail.available` / `unavailableReason`)与请求面
+ * ({@link requireRepoClient} 的 501 拒绝臂,三处调用点)都只从这里取值——两处各写一份就是本仓反复
+ * 吃过的「同一语义两个属主」病:判据一漂,列举面开始说谎而没人先红。一致性由 capabilities.test 的
+ * **对表格**逐名钉住(`available:false` ⟺ 良性请求真吃 501),而不是靠这段注释。
+ *
+ * 判据键 = **toolset**:内建详情与 center 条目都带这个字段,故两条产线天然共用同一份判据。
+ * `requiresRepo` 的 toolset 需要部署配好 git 后端(`GIT_API_BASEURL` ⇒ `deps.repoClient`)。
+ * 词表外的 toolset(内建的 `full-body`/`team`)不依赖后端 ⇒ 恒可用。
+ */
+export function scenarioAvailability(deps, toolset) {
+    if (TOOLSETS[toolset]?.requiresRepo === true && deps.repoClient === undefined) {
+        return { available: false, reason: "git_client_unconfigured" };
+    }
+    return SCENARIO_AVAILABLE;
+}
+/** 拒绝文案的唯一属主:闭集穷举 switch(新增原因词不在这里表态即编译红)。 */
+export function scenarioUnavailableMessage(reason, scenarioLabel) {
+    switch (reason) {
+        case "git_client_unconfigured":
+            return `${scenarioLabel} scenario needs GIT_API_BASEURL configured`;
+    }
+}
+/** repo 型场景取 git 客户端的唯一口(三处场景工厂同源)。不可用 ⇒ 按属主给的原因与文案 501 响亮拒。 */
+function requireRepoClient(deps, scenarioLabel) {
+    const client = deps.repoClient;
+    if (client !== undefined)
+        return client;
+    const verdict = scenarioAvailability(deps, "repo-readonly");
+    // 判成 available 却没有客户端 = 属主与消费面脱钩(对表格会先红)。此处仍 fail-loud,不静默放行。
+    throw new HttpError(501, verdict.available
+        ? `${scenarioLabel} scenario has no repo client although the availability owner reports it available (wiring defect)`
+        : scenarioUnavailableMessage(verdict.reason, scenarioLabel));
+}
 export const SCENARIO_NAME_RE = /^[a-z][a-z0-9-]{1,31}$/;
 // ([1053] registry-core 0.10.15:SCENARIO_PROMPT_MAX 随 ScenarioEntry.prompt 一并退役)
 /**
@@ -316,6 +380,7 @@ export function centerScenarios(deps, specs, builtinNames, logger) {
         const name = spec.name;
         overlay[name] = (req) => ({
             tools: toolset.build(deps, req),
+            hands: toolset.hands, // #196:表态随 toolset 走(center 声明面不可自选 hands —— 能力仍是代码定死的)
             skills: skillsForScenario(deps.skills, name),
         });
         if (builtinNames.includes(name))
@@ -324,13 +389,12 @@ export function centerScenarios(deps, specs, builtinNames, logger) {
     return { overlay, shadows };
 }
 function codeReview(deps, req) {
-    if (!deps.repoClient)
-        throw new HttpError(501, "code-review scenario needs GIT_API_BASEURL configured");
+    const repoClient = requireRepoClient(deps, "code-review");
     if (typeof req.repo !== "string" || !req.repo.trim()) {
         throw new HttpError(400, "code-review scenario requires a 'repo' field (owner/name or repo URL)");
     }
     const coords = parseRepo(req.repo);
-    const repoTools = repoToolsFor(deps.repoClient, coords);
+    const repoTools = repoToolsFor(repoClient, coords);
     const skills = skillsForScenario(deps.skills, "code-review");
     const objective = typeof req.objective === "string" ? req.objective : "Review this repository.";
     // Tiering: `council: true` runs the multi-lens council (L1 parallel lenses + L3 arbiter) — for
@@ -340,11 +404,14 @@ function codeReview(deps, req) {
     // (deterministic + cheaper + cacheable; see design/35). For OPEN-ENDED tasks where the decomposition
     // isn't known, core's `createSubagentTool` (model-driven self-delegation, with maxDepth / isolated
     // context / compressed-report guardrails) is the right tool — wire it in a dedicated scenario then.
+    // #196:两条腿(直评 / council)都声明 none —— 直评腿的 lead 只读仓库工具,council 腿的 lead 只调
+    // run_council;lens/arbiter 子任务同样只读仓库,故 council 工具拿无手 subRunner。
+    const hands = "none";
     if (req.council === true) {
         const rounds = clampRounds(req.rounds); // finite-guarded (NaN/±Inf → undefined → council default 1)
         return {
             tools: [
-                createCouncilTool(deps.subRunner, repoTools, objective, {
+                createCouncilTool(subRunnerFor(deps, hands), repoTools, objective, {
                     metrics: deps.metrics,
                     logger: deps.logger,
                     debate: req.debate === true, // L1+L2+L3 (peer debate) vs L1+L3
@@ -355,11 +422,12 @@ function codeReview(deps, req) {
                     ...(rounds !== undefined ? { rounds } : {}),
                 }),
             ],
+            hands,
             skills,
             promptProvider: coordinatorPrompt,
         };
     }
-    return { tools: repoTools, skills, promptProvider: directReviewerPrompt };
+    return { tools: repoTools, hands, skills, promptProvider: directReviewerPrompt };
 }
 const reviewBody = "Produce ONE prioritized review: a short summary, then findings grouped by severity " +
     "(blocker / major / minor), each with `path:line`, the problem, and a concrete fix. Cite real code — never invent files or symbols.";

package/dist/config-provider.d.ts

@@ -98,6 +98,7 @@ export declare class RemoteConfigProvider implements ConfigProvider {
  * version as the etag (so the caller's "skip re-apply if etag unchanged" works locally too).
  */
 export declare class LocalConfigProvider implements ConfigProvider {
+    #private;
     readonly kind: "local";
     private readonly store;
     /** [875]b 可观测性:config_loaded 日志要能回答「到底读的哪个目录」——复验实录:只设 LOCAL_DATA_ROOT 时

package/dist/config-provider.js

@@ -131,8 +131,12 @@ export class LocalConfigProvider {
     /** [875]b 可观测性:config_loaded 日志要能回答「到底读的哪个目录」——复验实录:只设 LOCAL_DATA_ROOT 时
      *  config.d 静默读不到且 0 模型无告警(CONFIG_LOCAL_DIR 才是本 lane 的选目录旋钮)。 */
     root;
+    /** 注入 store(测试缝)时保持其自带行为;自建时 fetchEffective 每次按调用铸新 store 挂 warning 座
+     *  (见 fetchEffective 头注)。 */
+    #injectedStore;
     constructor(root, store) {
         this.root = root;
+        this.#injectedStore = store;
         this.store = store ?? new FileConfigStore(root);
     }
     async fetchEffective(etag) {
@@ -146,7 +150,20 @@ export class LocalConfigProvider {
         // [898] tolerant read(0.10.12):catalog 域坏文件 ⇒ 该域 default+domainErrors 单列(不再连坐整包回落
         // env);gate 域坏文件仍 throw(走 caller 的整包 catch)。坏文件文本 hash 参与 version(坏≠absent、
         // 坏→修好均 bump),304-skip 纪律不漏拍——所以坏域场景下 etag 对比照旧安全。
-        const { effective: eff, domainErrors } = await this.store.getEffective({ tolerant: true });
+        // [3073]#204④:判形失败(schema 坏形/重名条目)走的是 buildEffective 的 `onWarning`(parse 层落
+        // default),不走 READ 层 throw——不接这个座,domainErrors 恒空,域被静默清空而排障 hint 只能谎报
+        // 「文件空」。warning 座是 store 构造级而 fetch 可能重叠(boot 超窗后台腿 vs 首拍 refresh),
+        // 共享缓冲会把别次快照的警告错记到本次结果(codex F2)——故自建形每次 fetch 铸新 store 配本地
+        // 收集器(FileConfigStore 无跨调用状态,按次构造零成本);注入 store(测试缝)保持其自带行为。
+        const parseWarnings = [];
+        const store = this.#injectedStore ??
+            new FileConfigStore(this.root, {
+                onWarning: (w) => {
+                    if (w.kind === "domain-defaulted")
+                        parseWarnings.push({ domain: w.domain, error: w.error instanceof Error ? w.error.message : String(w.error) });
+                },
+            });
+        const { effective: eff, domainErrors } = await store.getEffective({ tolerant: true });
         const tag = String(eff.version);
         if (etag !== undefined && etag === tag)
             return null; // unchanged → mirror remote 304
@@ -157,14 +174,17 @@ export class LocalConfigProvider {
         // The resolver gets THIS snapshot's domain values as `pending` (builder output is default-filled for
         // every domain), so the check never re-reads config.d — the one-atomic-snapshot invariant above holds.
         const refErrors = [];
-        const resolve = siblingResolver(this.store, eff);
+        const resolve = siblingResolver(store, eff);
         for (const d of ["rosters", "workers", "models", "collab", "systems", "entitlement"]) {
             const issues = await refIntegrityIssues(d, eff[d], resolve);
             // path CLEAR (locates the entry) + message operand-fingerprinted (see redactConfigError).
             if (issues.length > 0)
                 refErrors.push({ domain: d, error: issues.map((i) => `${i.path.join(".")}: ${redactConfigError(i.message)}`).join("; ") });
         }
-        const errors = [...domainErrors.map((de) => ({ domain: de.domain, error: redactConfigError(de.error) })), ...refErrors];
+        // parse 层判形失败与 READ 层坏文件同渠道:两者都是「坏域落 default」,候选门(§9.5-5)与排障 hint
+        // 需要同样看见——此前判形失败静默(domainErrors 空+域被清空),比坏文件更隐蔽。
+        const parseErrors = parseWarnings.map((w) => ({ domain: w.domain, error: redactConfigError(w.error) }));
+        const errors = [...domainErrors.map((de) => ({ domain: de.domain, error: redactConfigError(de.error) })), ...parseErrors, ...refErrors];
         return { effective: mapToServiceEffective(eff, eff.version), etag: tag, ...(errors.length > 0 ? { domainErrors: errors } : {}) };
     }
     async fetchSkillContent(contentHash) {

package/dist/config-types.d.ts

@@ -70,7 +70,8 @@ export interface ImageBakeConfig {
      *  `repo = ${registry}/${profile}` matches the P1 seed convention (seed-image-index.ts) and the index id
      *  `sha256(repo@digest)` is stable across seed and bake. `BAKE_IMAGE_REGISTRY` env; **code default = null**
      *  ⇒ the host-less `sema-images/<profile>` (node-local, documented non-pullable). Fleet posture (clay 拍
-     *  2026-07-13, SWR 弃用): `docker.io/claybobby`(海外主源;CN 兜底=内网 Gitea registry)。 */
+     *  2026-07-13, SWR 弃用; 2026-08 内网 Gitea registry 容器已下线全删): `docker.io/claybobby`(唯一在跑
+     *  的公共源;无内建 CN 兜底,国内网络不通的部署需自行配置 dockerd `registry-mirrors` 或自建 registry)。 */
     registry: string | null;
     /** The build-host promoted fetch-once cache base injected as `--cache-base` (NEVER caller-settable — a foreign
      *  origin would defeat the domestic-only iron rule). `BAKE_CACHE_BASE` (e.g. `http://<build-host>:<port>`). */
@@ -769,8 +770,9 @@ export interface ServiceConfigFlat {
      *  ⚠️ 非法模式(不含任何路径段,如 `"/"`)在 boot 期 fail-loud(createResolveSpec 先编译一次)——
      *  **对存量部署是行为变更**:搬家前这种坏值只在 default/auto/acceptEdits 三臂上每请求炸,只跑
      *  headless 的部署带着坏值也能起服务;现在起不来(方向=运维当场看见,而不是每任务一条 500)。
-     *  ⚠️ 沙箱 lane 的相对形写目标有一格今天无人裁决(cwd 里的守卫段看不见)——边界与两条收口路
-     *  成文在 boot/resolve-spec.ts 的 `RelativeTargetLexicalEnv` 类注。 */
+     *  ✅ 旧注写的「沙箱 lane 相对形有一格无人裁决(cwd 里的守卫段看不见)」自 core 5.19.0(#108)起
+     *  已收口:守卫按 `ToolCallRequest.cwd` 解析写目标,两条 lane 同得。剩余射程边界(引擎未盖戳的直接
+     *  调用形)成文在 `deployment-governance.ts` 的 `RelativeTargetLexicalEnv` 类注。 */
     sensitiveWritePatterns: string[];
     /** [1557]§四 opt-in (cli[1555]② finding, core[1556] suggested mechanism): the CC manual-family permission
      *  modes (default/auto/acceptEdits) gate every fs WRITE hand tool (Write/Edit/NotebookEdit) but never touched

package/dist/config.js

@@ -1215,7 +1215,7 @@ function parseOrchestrationDomain(ctx) {
     hostBackgroundShellEnabled();
     hostExecSpoolEnabled();
     // ── design/158 B4 ③ — LSP: one knob per lane. `LSP_ENABLED` used to drive BOTH the sandbox lane (opt-in,
-    // default OFF — it needs a baked `sema-code-lsp` template) and the host lane (opt-out, default ON — it needs
+    // default OFF — it needs a baked `ai-agent-code-lsp` template) and the host lane (opt-out, default ON — it needs
     // nothing and degrades to grep/read), i.e. one env name with two OPPOSITE defaults and no way to silence the
     // host lane without also naming the sandbox knob. `LSP_HOST_ENABLED` now owns the host lane; an explicit
     // `LSP_ENABLED=false` keeps working as a host opt-out (it was the only one operators ever had) with a notice
@@ -1347,8 +1347,9 @@ function parseOrchestrationDomain(ctx) {
                                             }
                                             : // DUAL-MODE §5: `local-docker` = a per-task container on THIS machine's docker daemon (isolation:true,
                                                 // suspendable:false). DOCKER_IMAGE is REQUIRED — no docker.io default (domestic-images iron rule); a
-                                                // deployment points it at the docker.io/claybobby public pool or an in-network mirror (SWR
-                                                // deprecated). Secrets are env-NAMEs the worker resolves from its
+                                                // deployment points it at the docker.io/claybobby public pool or its own private registry (SWR
+                                                // deprecated; the in-network Gitea registry container was retired 2026-08, no CN fallback baked
+                                                // in). Secrets are env-NAMEs the worker resolves from its
                                                 // own process.env (DOCKER_SANDBOX_ENV, a CSV of NAMEs) — never the values in the spec/center.
                                                 process.env.REMOTE_EXEC === "local-docker" && process.env.DOCKER_IMAGE
                                                     ? {
@@ -1427,7 +1428,7 @@ function parseOrchestrationDomain(ctx) {
         selectEnvironmentTool: boolEnv("SELECT_ENVIRONMENT_TOOL", true), // RFC A2: default ON (mount additionally gated on k8s+catalog)
         envFactsEnabled: boolEnv("SANDBOX_ENV_FACTS", true), // RFC A1: default ON (core 1.240.0 TaskSpec.envFacts; no-facts = no field)
         toolDeferLongtail: boolEnv("TOOL_DEFER_LONGTAIL", false), // [803]④ defer face: EXPERIMENTAL, default OFF
-        lspEnabled: boolEnv("LSP_ENABLED", false), // sandbox lane: opt-in (needs a baked sema-code-lsp template)
+        lspEnabled: boolEnv("LSP_ENABLED", false), // sandbox lane: opt-in (needs a baked ai-agent-code-lsp template)
         lspHostEnabled, // host lane: LSP_HOST_ENABLED, DEFAULT ON (CC-parity, degrades gracefully) — see the derivation above
         workflowAgentsReadOnly: boolEnv("WORKFLOW_AGENTS_READONLY", false), // [824]① TOB 保守旋钮:默认 off = workflow 子 agent 同权(CC parity)
         imageBakes: {

package/dist/deployment-governance.d.ts

@@ -0,0 +1,168 @@
+import { FileError, StubExecutionEnv, type ExecutionEnv, type Result, type ToolPolicy } from "@sema-agent/core";
+import { type DurableAskOptions } from "./approval.js";
+import type { ServiceConfig } from "./config.js";
+import type { applyRuntimeGovernance } from "./runtime-governance.js";
+/** `applyRuntimeGovernance` 的 governance 实参 —— 从折叠属主的签名位**推导**,不复制形状
+ *  (改一处签名,本口跟着变;两份手写形状正是漂移的成因)。 */
+export type DeploymentGovernanceInputs = Parameters<typeof applyRuntimeGovernance>[1];
+/** 本口读的部署配置切面(`ServiceConfig` 结构满足;窄接口让消费腿与测试不必铸整只 config)。 */
+export interface DeploymentGovernanceConfigView {
+    readonly autonomy?: ServiceConfig["autonomy"];
+    readonly commandPolicy?: ServiceConfig["commandPolicy"];
+    readonly manualModeShellGate?: ServiceConfig["manualModeShellGate"];
+    readonly sensitiveWritePatterns: ServiceConfig["sensitiveWritePatterns"];
+}
+/** 审批基线读的配置切面(同上,窄接口)。 */
+export interface ApprovalBaselineConfigView {
+    readonly approvalRequire: ServiceConfig["approvalRequire"];
+    readonly approvalDeny: ServiceConfig["approvalDeny"];
+    readonly approvalAutoBudget: ServiceConfig["approvalAutoBudget"];
+    readonly approvalNeverAuto: ServiceConfig["approvalNeverAuto"];
+}
+/** 守卫集裁决的 env/cwd 基准。**lane 分形归调用腿**(host 真 fs / 沙箱 deferred 代理 / run-local
+ *  workspace)—— 那是消费腿的属主知识,本口不重复它,只按 cwd 的在场性决定要不要补词法臂。 */
+export interface PathAdjudication {
+    /** 守卫策略 canonicalize 每一个写目标用的 env。 */
+    readonly env: ExecutionEnv;
+    /** 相对路径基准(core 的 `rootPath`)。缺席 ⇒ 相对形在真身那层判不了,补词法臂(见下)。 */
+    readonly cwd?: string;
+}
+/** #152([2703] 案二):durable 部署上的 AskUserQuestion 门的活体面探针(QuestionCoordinator 的切面)。 */
+export interface LiveQuestionFace {
+    hasLiveContext(): boolean;
+}
+/** durable 轴的审批基线入参。缺席 ⇒ adjudicated allow-all 基线(见 {@link createApprovalBaselinePolicy})。 */
+export interface DurableApprovalSeat {
+    /** 活体问答面;`undefined` ⇒ 恒 durable park 的原形门。 */
+    readonly question: LiveQuestionFace | undefined;
+    /** 每会话「本会话不再询问」探针(canonical toolName 键空间)。 */
+    readonly exempt?: DurableAskOptions["exempt"];
+    /** 豁免短路时的审计钩子。 */
+    readonly onExempted?: DurableAskOptions["onExempted"];
+}
+/**
+ * #152([2703] 案二):durable 部署上的 AskUserQuestion 门。活体面(QuestionCoordinator)缺席 ⇒ 原形
+ * `createDurableQuestionPolicy()`(恒 ask ⇒ 恒 durable park)。在场 ⇒ **判决时**按活流上下文分腿:
+ * 活流腿(bg/SSE,coordinator.runWithContext 包裹且投递面此刻可达,ALS 判)allow——工具执行落到
+ * RunnerDeps.onQuestion 的 coordinator,问正在 tail 流的活人;无活流腿(sync /v1/tasks、verify/cascade、
+ * durable resume 驱动、断连后的 detach 腿)ask——durable park 原语义逐字保留(#166 后无活流腿放行执行
+ * 也不会产出空答:coordinator 无 ALS ctx ⇒ 冻结 `{kind:"unavailable"}`(src/question.ts),永不悬挂;
+ * park 仍是把问题送到人面前的唯一那条腿,正当性不变、只是反事实前提换了)。
+ * 工具名字面量与 server.ts 的 pre-CAS 守卫同源("AskUserQuestion",core 未根导出常量)。
+ * ⚠️ **单一属主**(复审 A2):AskUserQuestion 的 durable 判决只有这一处。任何需要「同参重建」这条判决的
+ * 地方(main.ts 的 parkedReviveInheritedGate 父约束链)必须调本工厂,不得自折 core 原形——两份拷贝里
+ * 只改一份正是本条 finding 的成因。**登记豁免一处**:leader worker 腿(src/leader/wire.ts provisionWorker)
+ * 自折 core 原形——该腿无活体问答面可装且 leader 不 import boot 层(分层),core 原形+sentinel 即其完整
+ * 语义;豁免注在彼处互指,接活体面之日必须并回本工厂。
+ */
+export declare function createDurableQuestionGate(live: LiveQuestionFace | undefined): ToolPolicy;
+/**
+ * 沙箱 lane 上**相对形**写目标的守卫补层用 env(codex 对抗复审 round1 finding 1,红先复现)。
+ *
+ * 缺口:沙箱 lane 的守卫策略拿不到 `rootPath`(沙箱 cwd 不是 server 能猜的,#165 裁定 1),而
+ * `DeferredSandboxPathEnv.absolutePath` 对相对形一律报错。core 的 `canonicalizeTarget` 在
+ * **absolutePath 失败**这一支不置 `unresolvedSymlink`,于是守卫策略走的是
+ * 「判不了就弃权」的 `allow`(dist 亲读)。写门在场时这条腿被门的 `ask` 兜住;而
+ * `bypassPermissions` / settings 缺席这几形**根本没有门**,于是 `Write(file_path: ".env")` 一路放行——
+ * 而 core 的结构化写工具会把相对形按 engine 跟踪的 cwd 解析后真写下去(fs-write.js `resolveKey`)。
+ *
+ * 补法:**同一只**守卫策略工厂再铸一个实例,只把「路径→canonical key」这一步换成
+ * 纯词法基准(本 env)。判定与提取(哪个参数是写目标、NotebookEdit 的 notebook_path 优先、段匹配)
+ * 全部仍是 core 的,server 侧零复刻——复刻 core 的裁决逻辑正是「同源谎」那一类错误。
+ *
+ * 三条不可动的边界:
+ *  · **绝对形一律弃权**(absolutePath 报错 ⇒ canon 失败且非 unresolvedSymlink ⇒ core 判 allow):
+ *    绝对形归真身裁决那一层,#165「真身胜过名字」的裁定(域内良性软链名叫 `.ssh` 只 ask)不受影响。
+ *  · **只会 deny,不会放行**:相对形自身拼写里出现的段,解析成绝对路径后仍在,所以词法命中即真命中;
+ *    反过来一条名叫 `.env` 而真身良性的相对软链会被误 deny —— 方向是 fail-closed,与守卫集语义同向。
+ *  · **覆盖面(2026-08-08 按 core 5.19.0 #108 校正;旧文见下方「历史」段)**:本层只在
+ *    `ToolCallRequest.cwd` **缺席**那一形上说话。core 5.19.0 起每条路径解析型守卫按 `req.cwd ?? rootPath`
+ *    解析写目标(dist `core/sensitive-path-policy.js`),而 `canonicalizeTarget` 拿到 baseCwd 后会先把
+ *    相对形**拼成绝对形**再交给 env(dist `tools/fs/safety.js` 的 `baseCwd && !isAbsolutePathForm(...)`
+ *    分支)—— 本层的 `absolutePath` 对绝对形一律报错弃权 ⇒ **有戳时本层自动让位**,由真身那一层
+ *    (沙箱 `DeferredSandboxPathEnv` / host `NodeExecutionEnv`)按活 cwd 裁决,cwd 里的守卫段现在真看得见。
+ *    ⇒ 本层今天的射程 = 「引擎没盖戳」的调用:相对形**自身拼写**里带守卫段的那一类(`Write(".env")`、
+ *    `Write("cfg/.ssh/id_rsa")`),仍由本层 fail-closed 兜住。**不删臂**:让位与冗余不是一回事——
+ *    删掉它等于把「缺戳即无守卫」写死,而缺戳形在契约上是 core 明确保留的回落语义(直接调用形)。
+ *    两处特征化钉现在各带两臂(带戳 deny / 缺戳 allow):test/task-settings.test.ts 与
+ *    test/run-local.test.ts(后者是真引擎端到端,已翻成 🔴 正控)。
+ *
+ *    📜 **历史(留档,别当现状读)**:2026-08-08 之前本层的覆盖面到「cwd 里的守卫段看不见」为止——
+ *    本层把相对形挂在 `/` 上,而工具挂在 engine 活 cwd 上,`cd .git` 后 `Write("config")` 真写
+ *    `<root>/.git/config` 而本层只看得到 `/config` ⇒ 弃权。design/181 刀3 的口径更正查明这条残余面
+ *    **不是沙箱 lane 局部的**:host 腿虽供了 `rootPath`,那也是装配期的静态值,一样追不上被 Bash `cd`
+ *    就地改写的 `cwdRef.current`(run-local 端到端真复现:`cd .git/hooks` 后 `Write("pre-commit")` 真落盘)。
+ *    当年判定属主是引擎那条缝(不是任何一条消费腿——在消费腿里自己拿静态 cwd 追 `cd`,是拿会漂的复制品
+ *    追引擎的真值,本文件反复点名的病),并把两条钉写成「引擎缝落地后一起翻面」。**该缝即 core backlog
+ *    #108,已在 5.19.0 到货**,两条钉按上述翻面完毕。另一条备选收口(守卫集开启即把沙箱 lane 相对写
+ *    一律 deny,有真受损方且无对应旋钮)因此作废,无需部署方拍板。
+ */
+export declare class RelativeTargetLexicalEnv extends StubExecutionEnv {
+    /** 相对形 → `/<词法归一>`;绝对形 / 空串 / 含 NUL 一律报错(= 弃权,见类注)。 */
+    absolutePath(path: string): Promise<Result<string, FileError>>;
+    /** 恒「不存在」⇒ core 的 `canonicalizeNewPath` 逐级回退,最终把词法归一形当 canonical key 交给段匹配。
+     *  这里绝不能报错:报错会被 core 读成 `unresolvedSymlink` 而对**每一个**相对目标 deny(含普通文件)。 */
+    exists(_path: string, _abortSignal?: AbortSignal): Promise<Result<boolean, FileError>>;
+}
+/**
+ * boot 期的守卫集**可编译性**门(#177 收口①,随 design/181 件一搬进本口 —— 三条消费腿同得)。
+ *
+ * 守卫集的编译发生在**每个请求**上。core 的 `compilePatterns` 对「一个路径段都没有」的模式(`"/"`、
+ * `"//"`)THROW,那条 throw 会变成**每一个任务一条 500**,且运维从错误里看不出是自己的 env 写错了。
+ * 消费腿在装配期先编译一次:非法旋钮值当场炸在启动上(与 config.ts 的 env fail-loud 同族),指名键与
+ * core 的原因。env 只是编译期的占位(compilePatterns 不碰它),真裁决用的是每请求按 lane 铸的那一个。
+ */
+export declare function assertGuardPatternsUsable(config: Pick<DeploymentGovernanceConfigView, "sensitiveWritePatterns">): void;
+/** 一条 boot 期运维告警的**载荷**(纯数据 ⇒ `build*`;打给谁、用哪只 logger 归消费腿)。 */
+export interface OperatorWarning {
+    readonly event: string;
+    readonly fields: Record<string, unknown>;
+}
+/** {@link buildOnlySensitiveBaselineWarning} 读的座位量 —— 「这个部署到底有没有一道**真**门」。 */
+export interface GateSeatView {
+    /** durable 审批门(checkpoint suspend/resume)是否在这条腿上真装。 */
+    readonly durableEnabled: boolean;
+    /** 单用户 turnkey 的 auto-accept 基线是否适用(= 零门意图的既定姿势,不是 misconfig)。 */
+    readonly singleUserAutoAcceptBaseline: boolean;
+}
+/**
+ * UNGATED 信号的**补偿**(design/181 件一收编 / 件三三腿同得)。
+ *
+ * 审批基线铺开之后 core 的 `hasEffectAwareGate` 恒真,于是它那条 "write-capable hand tools are present
+ * but UNGATED" 的 onError 不再触发(判据是 `policyLayers.length > 0`,prepare-task dist 亲读)。那条信号
+ * 此前是「这个部署一个门都没接」这个 misconfig 的**唯一**提示,而守卫集只挡那二十来个路径段、其余写
+ * 目标照旧无裁决 —— 信号不能因为我们铺了基线就静默消失,所以由我们自己按同一判据说一次。
+ *
+ * 判据(与信号消失的条件逐字互补):守卫集在场 ∧ 两条产**真**门的腿都不在场(durable 门关 ∧ 单用户
+ * auto-accept 基线不适用)。三个量都是部署常量 ⇒ 消费腿在 boot 期说一次,不是每任务一次。
+ *
+ * ⚠️ 单一属主(design/181 件三):HTTP 腿与 run-local 腿共用本判据与文案。两处各写一份 = 一处改了另一处
+ * 没改,而两份都长得像对的 —— 那正是本文件存在的理由。
+ */
+export declare function buildOnlySensitiveBaselineWarning(config: Pick<DeploymentGovernanceConfigView, "sensitiveWritePatterns">, seat: GateSeatView): OperatorWarning | undefined;
+/**
+ * `applyRuntimeGovernance` 的 governance 实参预铸(design/181 件一)。
+ *
+ * 键存在性 profile 逐字保持消费腿原样:`autonomy`/`commandPolicy` 恒在场(值可为 `undefined`),
+ * `manualModeShellGate`/`sensitivePathPolicy` 按在场性条件展开 —— `applyRuntimeGovernance` 的
+ * `!== undefined` 判据对两者等价,但 profile 是折叠面的可观测字节,搬家不许顺手改。
+ */
+export declare function createDeploymentGovernanceInputs(config: DeploymentGovernanceConfigView, pathAdjudication: PathAdjudication): DeploymentGovernanceInputs;
+/**
+ * 审批基线 —— `applyRuntimeGovernance` 那个 base 的 `toolPolicy` 座(design/181 件一)。**恒非
+ * `undefined`**:治理层是 tighten-only 的叠加层,没有基线可叠时它自己也产不出「门在场」这件事。
+ *
+ * 两形:
+ *  · `durable` 在场 ⇒ durable 轴 = AskUserQuestion 判决门 + F4 高危写审批门(deny/neverAuto/预算/
+ *    会话豁免全在 `createDurableAskPolicy` 里)。gated `ask` 由 core 变成 durable checkpoint suspend。
+ *  · `durable` 缺席 ⇒ **adjudicated allow-all**(`createAllowDenyPolicy({})`):一条**在场的**、
+ *    effect-aware 的策略。CC 的信任模型是 auto-accept,但门**机制**必须在场(core 原则「机制留、默认
+ *    可更宽」)—— 满足 core 的 `hasEffectAwareGate`,恢复可观测性与 hook/tighten 点,而运维照旧用
+ *    `AUTONOMY`/`commandPolicy` 收紧不可逆操作(由 `applyRuntimeGovernance` tighten-only 叠上)。
+ *
+ * ⚠️ 「零门意图才铺 allow-all」这条准入判据**不在本口**:它是消费腿的部署形判断(单用户/多租户、
+ * 有无 checkpoint 店),属主是 `hasOperatorGateIntent`/`assertGateIntentServiceable`(src/approval.ts)。
+ * 本口只按调用方给的形铸策略,绝不替它判「这个部署该不该有门」。
+ */
+export declare function createApprovalBaselinePolicy(config: ApprovalBaselineConfigView, durable?: DurableApprovalSeat): ToolPolicy;
+//# sourceMappingURL=deployment-governance.d.ts.map