@sema-agent/server 7.78.1 → 7.79.0

package/README.md

@@ -114,6 +114,12 @@ curl -s localhost:8090/v1/tasks -H "Authorization: Bearer <SERVICE_AUTH_TOKEN>"
 # To pin a model: add "model":"<catalog id>" to the body; see GET /v1/capabilities for what is available
 ```
 
+- **Where your files have to be**: a caller-supplied `cwd` is a path on the machine the **server process**
+  runs on, and it is honored only on the single-user `REMOTE_EXEC=host` lane — that lane is by definition
+  *this* box (no container boundary). So "server on box A, my repo on box B" does not work: nothing maps
+  B's paths into A. Run the server on the box that holds the files (or `run-local` there), or use a
+  container lane (`e2b` / `k8s` / `local-docker`) where the workspace is the sandbox's own and `cwd` is
+  ignored.
 - **Distribution coordinates**: npm = [`@sema-agent/server`](https://www.npmjs.com/package/@sema-agent/server)
   (public on npmjs) · images = `ghcr.io/sema-agent/sema-server` + `docker.io/claybobby/sema-server`
   (both public; `:latest` rolling, `:<sha>` pinned).

package/USAGE.md

@@ -404,6 +404,10 @@ MODEL_CASCADE_LADDER=deepseek-flash,deepseek-pro   # 目录里的模型名,cheap
   `SERVICE_AUTH_TOKEN`/TOKENS 名录)⇒ 自动绑 `127.0.0.1`,boot 日志点名原因。理由:该形常配
   `REMOTE_EXEC=host`(用户真机、非沙箱),绑全接口=同网段任何人可无鉴权提交任务并执行。
 - 配了凭证的部署(云形/k8s/compose)缺省**不变**(全接口),既有部署零影响。
+- **跨机不映射 cwd**:请求里的 `cwd` 是**服务进程所在那台机器**上的路径,且只有单用户 `REMOTE_EXEC=host`
+  车道会尊重它(那条车道的定义就是"运维自己这台机、无容器边界")。所以「服务跑在 A 机、代码在 B 机」不成立
+  —— 没有任何东西把 B 的路径映到 A。要么把服务(或 `run-local`)跑在放着文件的那台机器上,要么走容器车道
+  (`e2b`/`k8s`/`local-docker`),那里的工作区是沙箱自己的,`cwd` 被忽略。
 
 **workspace 浏览面 —— 已随整树快照纪元退役**
 - 旧四端点(list/tree/file/archive)恒 `501 capability.workspace_retired`,`capabilities.workspace`

package/dist/approval-card.d.ts

@@ -21,7 +21,7 @@
  * 没有方法、没有捕获的行为。
  */
 import { z } from "zod";
-import { type AskEvidenceAbsence, type ReadRootGrantCandidate, type RuleOffer } from "@sema-agent/core";
+import { type AskEvidenceAbsence, type AskRequest as CoreAskRequest, type ReadRootGrantCandidate, type RuleOffer } from "@sema-agent/core";
 import type { AskRow } from "./plugins/approval-ask-store-sql.js";
 /** 模型自由文本(`sourceAgentName` / `delegation.agentName`)的限长(设计稿 §6.2)。设计 §3.1 把
  *  「限长 + 脱敏」写成 **server 新增责任**(引擎无此层):spawning model 挑的名字是自由文本,
@@ -322,14 +322,24 @@ export type RuleEvidenceProjection = z.infer<typeof RuleEvidenceSchema>;
  *  · `orgRevision` / 缺席词 verbatim(数值 / 闭集词,非内容)。
  */
 export declare function readRuleEvidence(req: unknown): RuleEvidenceProjection | undefined;
-/** [ref] 第五单(core [ref] 修②)—— `ruleOffers` 缺席因由的**闭三词集**(core d.ts 逐字;词表是闭集,
- *  未知词=形不合=按缺席处置,绝不透传一个消费端词表外的值)。 */
+/**
+ * [ref] 第五单(core [ref] 修②)—— `ruleOffers` 缺席因由的**闭三词集**。
+ *
+ * 🔴 **型从 core 派生,不手抄**(S-249):core 刻意**不导出**这个名字,也不导出运行期常量
+ * (`permission-rule-lanes.d.ts` 顶注逐字:「Deliberately not exported: this is a wire vocabulary, and its
+ * two faces declare it literally … so a consumer reads the closed set on the type it is holding」)——
+ * 于是本仓**必须**自持一份运行期词表(zod 要字面元组),但**不必**自持一份型。做法:型 =
+ * `AskRequest["ruleOffersAbsence"]` 的联合(那正是 core 要我们读的那张脸),运行期词表另立一行,
+ * 两者之间架**两向编译围栏** ⇒ core 加词 / 改词 / 退役任一,本文件当场 tsc 红。
+ * (对照 {@link AskEvidenceAbsenceSchema}:那一族 core **给了**运行期常量,所以那边零词表、用 `z.custom`。
+ * 两族的姿势不同不是分歧,是「上游给什么就用什么」的同一条纪律的两种兑现。)
+ */
+export type RuleOffersAbsence = NonNullable<CoreAskRequest["ruleOffersAbsence"]>;
 export declare const RuleOffersAbsenceSchema: z.ZodEnum<{
     mandated: "mandated";
     lane_cannot_speak: "lane_cannot_speak";
     shadowed: "shadowed";
 }>;
-export type RuleOffersAbsence = z.infer<typeof RuleOffersAbsenceSchema>;
 /**
  * `AskRequest.ruleOffersAbsence`(core [ref] 修②)的**边界窄读** —— 活卡帧与 `card_json` 的唯一铸造点
  * (与 {@link readProbeCause} 同款分工),两面结构性同值。闭集词 verbatim(非内容族,零 redact);

package/dist/approval-card.js

@@ -233,11 +233,18 @@ export function readRuleEvidence(req) {
         ...(raw.personalRuleDotsAbsent !== undefined ? { personalRuleDotsAbsent: raw.personalRuleDotsAbsent } : {}),
     };
 }
-export const RuleOffersAbsenceSchema = z.enum(["mandated", "lane_cannot_speak", "shadowed"]);
+const RULE_OFFERS_ABSENCE_VALUES = ["mandated", "lane_cannot_speak", "shadowed"];
+export const RuleOffersAbsenceSchema = z.enum(RULE_OFFERS_ABSENCE_VALUES);
 const RuleOffersAbsenceEnvelopeSchema = z.object({ ruleOffersAbsence: RuleOffersAbsenceSchema.optional() });
 export function readRuleOffersAbsence(req) {
     const parsed = RuleOffersAbsenceEnvelopeSchema.safeParse(req);
-    return parsed.success ? parsed.data.ruleOffersAbsence : undefined;
+    if (parsed.success)
+        return parsed.data.ruleOffersAbsence;
+    const raw = req !== null && typeof req === "object" ? req.ruleOffersAbsence : undefined;
+    if (raw === undefined)
+        return undefined;
+    recordFailOpen("server.approval-card.closed-word-out-of-set", `ruleOffersAbsence=${redactSecrets(String(raw)).slice(0, 40)}`);
+    return undefined;
 }
 const DenialLimitFallbackSchema = z
     .object({

package/dist/auto-mode-face.d.ts

@@ -1,17 +1,29 @@
-import { type Model, type ModelRoles, type RuntimeCaps } from "@sema-agent/core";
+import { type RunnerDeps, type RuntimeCaps } from "@sema-agent/core";
 import type { SettingsPermissionMode } from "./task-settings.js";
 /**
- * 分类器**配置**的模型路由 —— 直接复用 core 的 `resolveTaskModel({ modelRole: "classifier" })`(prepare-task 武装时
- * 走的同一函数:role 回落链 `classifier → summarize → default`,且 `{select}` 形 RoleSpec 按目录选型)。
- * codex r4 [medium] 验真后改:首版按名字级自算,遇 center 下发的 `{select:{tier}}` 形会错落到 summarize/default,
- * 对 `sema doctor permissions` 报另一个模型。答的是「配置了什么」;运行期 `derivedRouteFallsBack` 的回落不在射程
- * (那是 core 状态座的事)。什么都解不出 ⇒ `{id:undefined, fault}`(core 的拒句当数据交出,读面不写 model 键):
- * 本面是纯披露、不是执法——读面 500 掉整张能力表比少一个 model 键更伤。
+ * 分类器席的模型 —— **调 core 的单一解析器** `classifierSeatModel({deps, main})`(core 7.20.0 / [ref],
+ * 本仓 [ref] 的跨仓诉求兑现;契约句 `classifier.seat.one_resolver` 逐字:引擎的武装点与**显示这个席**
+ * 的宿主读面调同一只导出函数,而不是各自从目录/角色/档位表再推一遍 —— 第二份推导就是第二个答案)。
+ *
+ * 🔴 **S-350:本仓的自算分支已删**。修前这里调的是 `resolveTaskModel({modelRole:"classifier"})`,那只
+ * 回答的是「classifier **角色**解到谁」;引擎真正挑席时在角色没点名模型的情况下还要走 **tierBelowMain**
+ * (主模型档位**严格之下**、路由不同的最近一档)。两者在「档位表在场 + 没有 classifier 角色」这一形上
+ * 给出**不同的模型**(车FL U-3 坐实),读面于是对着 `sema doctor permissions` 报另一只模型。规则变少的
+ * 修法只有一条:把这个问题整个交回给上游的那一只解析器。
+ *
+ * 递进去的 `deps` 就是**交给 `Runner` 的那一只**(main.ts 递 `runnerDeps`):`models`/`roles`/`tiers` 三席
+ * 与引擎看到的是同一批**活引用**(center 原地热更新 ⇒ 读面按请求现算)。解析器对**原始**与**已展开**
+ * 两形 deps 同答(它自己 `normalizeSeatDeps` 一次 `expandTiers`),且**永不抛**。
+ *
+ * 唯一还会抛的是 `main` —— **这条 run 的主模型**,也就是本仓给一条没选模型的 task 铸的那个 ref
+ * ({@link DEFAULT_MODEL_REF};`boot/resolve-spec.ts` 每条 spec 都盖 `spec.model`,所以引擎眼里的 main
+ * 恒是它解出来的那一只,**不是** core 的 `default` **角色**链)。席是相对主模型定义的(tierBelowMain =
+ * 「主模型档位之下」),主模型解不出就没有席可言 ⇒ `{id:undefined, fault}`(core 的拒句当数据交出,读面
+ * 不写 model 键):本面是纯披露、不是执法——读面 500 掉整张能力表比少一个 model 键更伤。`main` 这一步
+ * 喂**展开**目录,与引擎构造期 `expandTiers(models, tiers)` 之后再解逐字同源(邻居惯例:
+ * `routes/capabilities.ts` 的 `workflowModels` / `/v1/models` 两处同法)。
  */
-export declare function classifierRouteFor(deps: {
-    models?: Record<string, Model>;
-    roles?: ModelRoles;
-}): ClassifierRoute;
+export declare function classifierRouteFor(deps: Pick<RunnerDeps, "models" | "roles" | "tiers">): ClassifierRoute;
 /** `classifierRouteFor` 的答:解出 ⇒ `{id}`;解不出 ⇒ `{id:undefined, fault}`(core 的拒句原文,不吞)。 */
 export type ClassifierRoute = {
     readonly id: string;

package/dist/auto-mode-face.js

@@ -2,10 +2,13 @@ import { createRequire } from "node:module";
 import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { z } from "zod";
-import { resolveTaskModel } from "@sema-agent/core";
+import { classifierSeatModel, expandTiers, resolveTaskModel } from "@sema-agent/core";
+import { DEFAULT_MODEL_REF } from "./model-select.js";
 export function classifierRouteFor(deps) {
     try {
-        return { id: resolveTaskModel({ modelRole: "classifier" }, deps).model.id };
+        const expanded = expandTiers(deps.models, deps.tiers ?? {}) ?? deps.models;
+        const main = resolveTaskModel({ model: DEFAULT_MODEL_REF }, { ...deps, ...(expanded !== undefined ? { models: expanded } : {}) }).model;
+        return { id: classifierSeatModel({ deps, main }).model.id };
     }
     catch (err) {
         return { id: undefined, fault: err instanceof Error ? err.message : String(err) };

package/dist/boot/deferred-sandbox-path-env.d.ts

@@ -1,3 +1,50 @@
+/**
+ * [ref] —— 沙箱 lane(e2b/k8s/ssh/adb/local-docker)写门的**真 env 裁决**接法。
+ *
+ * ## 缺口与它的形状
+ *
+ * core 的 `createFsWriteGatePolicy` / `createSensitivePathPolicy` 把每一个写目标交给
+ * `canonicalizeTarget(env, …)` 去问 fs 要真身(`absolutePath` → `exists` → `canonicalPath` →
+ * `fileInfo`/`readLink` 逐跳,dist 亲读)。host lane 上那个 env 就是 hand 工具真正写的那块盘。
+ * 沙箱 lane 不是:per-task 的沙箱 env 由 core 的 `executionEnvFactory` 在 spec **之后**才铸,
+ * 而写门 wiring 必须在 spec 期就交出去。
+ *
+ * 出路不是把裁决搬去 hook 层(那要在本仓复刻 `canonicalizeTarget` 的逐级 exists / symlink 解析 /
+ * 段匹配 / 折叠序——复制 core 的裁决逻辑=同源谎),而是利用一个部署事实:**那个 per-task 沙箱 env
+ * 本来就是本仓铸的**。于是本模块给写门一个 ExecutionEnv **代理**:它在**调用时刻**(runToolGate 裁决,
+ * 必在 prepare 之后)去 slot 里取该 task 的真 env 并转发 fs 读原语。call-time 转发消除了时序问题,
+ * 与「从调用上下文读 env」是同一性质。
+ *
+ * ## 三条不可动的裁定
+ *
+ *  1. **`absolutePath` 一面不转发**,沿用词法规则(POSIX 绝对形归一 / NUL 拒 / 非绝对形 err)。
+ *     真 env 的 `absolutePath` 会按 **env 自己的 cwd** 解析相对路径,而工具真写处按 engine 跟踪的
+ *     cwd 解析——两个基准不同,转发它等于拿错基准铸 canonical key,而**错误的 allow 比没有门更糟**。
+ *     相对形 / `~` / 盘符形因此照旧 err ⇒ `canonicalizeTarget` 失败 ⇒ 写门 `ask`(fail-closed)。
+ *     「不猜沙箱工作目录」这条公理不随真 env 到场而松。
+ *  2. **slot 空 = fail-closed 且响亮**:转发面返回错误 ⇒ core 把 `exists` 报错读成
+ *     `unresolvedSymlink` ⇒ `createSensitivePathPolicy` 判 deny、写门判 ask,折叠后 deny 恒赢。
+ *     保护型缺席的失败方向必须与能力语义同向。留痕走结构化 `warn`(每实例一次)而**不**走
+ *     `observability/fail-open.ts`:那个词表按其模块头是 `F`(体验/缓存回退)与 `P-DEBT`(明知方向
+ *     不对的保护型欠账)两类的准入面,本臂方向是**对的**(fail-closed),登记进去会把「已收口的
+ *     保护臂」混进「待还的债」计数里。
+ *  3. **slot 只认「当前活腿」**:同一 session 同时只有一条活腿(HTTP `conflict.session_active_run` +
+ *     core session acquire 双重串行化;委派子代另用一个 sessionId),所以同键改铸即顶替旧登记——
+ *     那些旧登记来自 park-only 之类「不 destroy 也不 suspend」的终局,留着只会让 resume 腿失去真身裁决。
+ *
+ * ## slot 的键 = sessionId
+ *
+ * 工厂 ctx 只有 `{sessionId, taskId?, isolation?, parentCwd?}`(core `ExecutionEnvFactoryContext`),
+ * 而 `/v1/runs` 会在 resolveSpec **之后**铸自己的持久 taskId 覆盖 `spec.taskId`,所以 taskId 在主路径
+ * 上对不上——sessionId 是两侧都稳的那一个(per-task 镜像登记簿是同一个先例)。
+ * 委派子任务(Agent / workflow 子代)拿的是**另一个** sessionId,所以父的 slot 不会被子代覆盖(「不许
+ * 最后写赢」由此成立)。**残余面**:子代的写仍按**父**的 env 裁决——子代的 policy 就是父的那一个实例
+ * (core `inheritedGateForChildren` 把它当 parentConstraint 继承),而 policy 收到的只有
+ * `{toolName, args, toolCallId}`,读侧根本没有腿身份可键控。方向上它逼近真相而非远离(过渡形是「谁的盘
+ * 都不看」),但有一条**新的松面**:父盘上一个名叫守卫段、真身良性的软链,会让子代在自己盘上指向真守卫段
+ * 的同名路径拿到父盘的宽松答案。收口需要一条「按当前工具调用的 env 裁决」的引擎缝,属设计件;
+ * 该面由 test/task-settings.test.ts 的「真身胜过名字」特征化钉机器可见。
+ */
 import { FileError, StubExecutionEnv, type ExecutionEnv, type ExecutionEnvFactory, type FileInfo, type Result } from "@sema-agent/core";
 /** 哪些 lane 用本模块的代理裁决写门 —— `REMOTE_EXEC` 未设(进程内 host)与显式 `host` 之外的全部。
  *  与 resolve-spec 的 `hostSemanticsLane` 是同一判别式的两面,取值处**只此一个**(两处各写一份正是漂移的成因)。 */

package/dist/boot/deferred-sandbox-path-env.js

@@ -1,12 +1,8 @@
-import { posix } from "node:path";
 import { FileError, StubExecutionEnv, err, ok } from "@sema-agent/core";
+import { normalizeAbsolutePathLexically } from "../task-cwd.js";
 export function isSandboxPathAdjudicationLane(provider) {
     return provider !== undefined && provider !== "host";
 }
-function normalizeAbsolutePathLexically(path) {
-    const collapsed = posix.normalize(path.replace(/^\/+/, "/"));
-    return collapsed.length > 1 ? collapsed.replace(/\/+$/, "") : collapsed;
-}
 const MAX_BOUND_SESSIONS = 4096;
 export class SandboxPathEnvSlots {
     bySession = new Map();

package/dist/boot/resolve-spec.js

@@ -1,6 +1,6 @@
 import { realpathSync } from "node:fs";
 import { join } from "node:path";
-import { NodeExecutionEnv, QUESTION_AWAITS_RESUME, deriveAskEffective, expandTiers, resolveAskSeamForm, tightenTaskSpec } from "@sema-agent/core";
+import { NodeExecutionEnv, QUESTION_AWAITS_RESUME, WRITE_EXEMPT_DIR_COVERS_ROOT_CODE, deriveAskEffective, expandTiers, resolveAskSeamForm, tightenTaskSpec } from "@sema-agent/core";
 import { cappedCeiling } from "../budget.js";
 import { centerPromptProvider, centerIdentityAssembled } from "../capabilities/center-prompts.js";
 import { SessionEnvironmentSelection, selectEnvironmentTool } from "../capabilities/select-environment-tool.js";
@@ -10,7 +10,7 @@ import { stampHandsLane, toolPolicyForHands } from "../capabilities/hands-lane.j
 import { shouldDiscloseNoPersistentMemory, withNoPersistentMemoryNotice } from "../capabilities/memory-notice.js";
 import { applyLongtailDefer } from "../capabilities/tool-defer.js";
 import { assertGuardPatternsUsable, buildOnlySensitiveBaselineWarning, createApprovalBaselinePolicy, createDeploymentGovernanceInputs } from "../deployment-governance.js";
-import { acceptShellScratchpadDir, buildEnvFacts, egressForRemoteExec, ensureScratchpadDir, resumeFactsForLane } from "../env-facts.js";
+import { acceptShellScratchpadDir, buildEnvFacts, egressForRemoteExec, ensureScratchpadDir, resumeFactsForLane, scratchpadCoveringTaskRoot } from "../env-facts.js";
 import { FleetEventBus } from "../fleet/fleet-bus.js";
 import { composeHooks, createTaskHooks } from "../hooks/hook-runner.js";
 import { headerStr } from "../http/principal-gate.js";
@@ -30,7 +30,7 @@ import { normalizeAttachments, normalizeResilience, normalizeResumeAtMode, norma
 import { cwdHonored, deviceCwdHonored, effectiveHostWorkspace, inProcessSingleUserLane, isValidCwd, parseAdditionalDirectories, satisfiedByProcessCwd, shellEnvMismatchCount } from "../task-cwd.js";
 import { assertRequestA2aUnlocked, resolveRequestA2a } from "../task-a2a.js";
 import { assertRequestMcpContentOrigin, assertRequestMcpUnlocked, resolveRequestMcp } from "../task-mcp.js";
-import { MAX_SETTINGS_OUTPUT_STYLE_CHARS, acceptAppendSystemPrompt, applyTaskSettings, effectivePermissionMode, effectiveThinking, hasConstitutionAnchors, parseTaskSettings, providerDropsAppend, shellGateForMode, withPermissionMode } from "../task-settings.js";
+import { MAX_SETTINGS_OUTPUT_STYLE_CHARS, acceptAppendSystemPrompt, applyTaskSettings, autoModeRequestedForMode, effectivePermissionMode, effectiveThinking, hasConstitutionAnchors, parseTaskSettings, providerDropsAppend, shellGateForMode, withPermissionMode, writeFaceForMode } from "../task-settings.js";
 import { enableForkFromBody, normalizeRetainSubagentSessions, selfOrchestrationFromBody } from "../task-workflow.js";
 import { redactSecrets } from "../trace/redact.js";
 import { DeferredSandboxPathEnv, isSandboxPathAdjudicationLane, sandboxPathEnvSlots } from "./deferred-sandbox-path-env.js";
@@ -46,6 +46,19 @@ export function createResolveSpec(ctx) {
         assertRequestMcpUnlocked(body.mcpServers, lockedKeys);
         if (opts?.leg === "fresh")
             assertRequestMcpContentOrigin(body.mcpServers);
+        if (opts?.leg === "fresh") {
+            const conflict = scratchpadCoveringTaskRoot({
+                cwd: body.cwd,
+                shellScratchpadDir: body.scratchpadDir,
+                localDataRoot: config.localDataRoot ?? localRoot,
+                sessionId: auth?.sessionId,
+                requirePrincipal: config.requirePrincipal,
+                cwdHonored: cwdHonored(config),
+            });
+            if (conflict) {
+                throw new HttpError(400, `cwd "${conflict.cwd.asSpelled}" is inside this session's scratchpad "${conflict.scratchpadDir.asSpelled}" — the scratchpad is the fs-write gate's EXEMPT directory, so a task rooted there would auto-approve every write under its own root and the engine refuses to build the gate at all (config.write_exempt_dir_covers_root). Point cwd at the project directory instead (or send no cwd and let the session keep the one it has): this session registers the cwd you send, so a task that happens not to mount the write gate would still leave every LATER task on this session rooted in the exemption. A workflow that really is meant to write without prompts says so with a knob that means it (a permission mode, an open write face) and still keeps its root outside the scratchpad — those knobs do not lift this refusal, because the conflict is between two fields of this request, not a permission level.`, { code: "request.field_conflict", extra: { cwd: conflict.cwd, scratchpadDir: conflict.scratchpadDir } });
+            }
+        }
         const rawMemoryCapture = body.memoryCapture;
         if (rawMemoryCapture !== undefined && rawMemoryCapture !== "off") {
             throw new HttpError(400, "memoryCapture must be the string 'off' when present (the session-level memory-capture opt-out declaration; absent = capture as usual — there is no 'on' spelling)", { code: "request.field_invalid" });
@@ -53,7 +66,7 @@ export function createResolveSpec(ctx) {
         assertRequestA2aUnlocked(body.a2aPeers, lockedKeys);
         const gated = await gateScenarioAndAppend(body, auth, opts);
         const effMode = effectivePermissionMode(body, gated.parsedSettings.settings);
-        noteSessionShellGate?.(auth?.sessionId, effMode === "bypassPermissions");
+        noteSessionShellGate?.(auth?.sessionId, effMode !== undefined && shellGateForMode(effMode) === "off");
         const lane = bindSettingsCwdEnvAndModel(body, auth, gated, effMode, opts);
         const anchors = await resolveHistoryAnchors(body, auth);
         const spec = assembleSpecLiteral(body, auth, req, opts, { ...gated, ...lane, ...anchors }, effMode);
@@ -279,8 +292,8 @@ export function createResolveSpec(ctx) {
             additionalReadDirectories,
             enablePlanMode: config.planModeEnabled ? true : undefined,
             ...(effMode ? { shellGate: shellGateForMode(effMode) } : {}),
-            ...(effMode === "bypassPermissions" ? { writeFace: "open" } : {}),
-            ...(effMode === "auto" ? { autoModeRequested: true } : {}),
+            ...((f) => (f !== undefined ? { writeFace: f } : {}))(effMode !== undefined ? writeFaceForMode(effMode) : undefined),
+            ...((f) => (f !== undefined ? { autoModeRequested: f } : {}))(effMode !== undefined ? autoModeRequestedForMode(effMode) : undefined),
             selfOrchestration: selfOrchestrationFromBody({ selfOrchestration: body.selfOrchestration === true || parsedSettings.settings?.ultracode === true }, config, Boolean(centerRuntimeCapsResolver)),
             forwardSubagentEvents: body.forwardSubagentEvents === true ? true : undefined,
             retainSubagentSessions: normalizeRetainSubagentSessions(body.retainSubagentSessions),
@@ -507,6 +520,12 @@ export function createResolveSpec(ctx) {
                 governed = applyTaskSettings(governedBase, effectiveSettings, fsWriteGate, workflowGate);
             }
             catch (e) {
+                if (e.code === WRITE_EXEMPT_DIR_COVERS_ROOT_CODE) {
+                    throw new HttpError(400, e.message, {
+                        code: "request.field_conflict",
+                        ...(e.detail !== undefined ? { extra: { writeExemptDirCoversRoot: e.detail } } : {}),
+                    });
+                }
                 throw new HttpError(422, `settings are tighten-only and cannot loosen the deployment policy: ${e.message}`);
             }
         }

package/dist/capabilities/code-review-council.js

@@ -1,4 +1,5 @@
 import { Type } from "typebox";
+import { DEFAULT_MODEL_REF } from "../model-select.js";
 import { runTeamDiscussion } from "@sema-agent/core";
 import { REVIEW_LENSES, GROUNDING, LENS_SYSTEM_TPL, DEBATE_MEMBER_TPL, DEBATE_TOPIC_TPL, ARBITER_SYSTEM, ARBITER_FALLBACK_HEADER } from "./prompts/code-review.js";
 const LENSES = REVIEW_LENSES;
@@ -79,7 +80,7 @@ async function runConvergence(subRunner, repoTools, objective, findings, opts, s
     if (opts.debate) {
         const team = await (opts.teamFn ?? runTeamDiscussion)({
             runner: subRunner,
-            model: "default",
+            model: DEFAULT_MODEL_REF,
             members: lenses.map((l) => ({ role: l.name, systemPrompt: debateMemberSystem(l) })),
             topic: debateTopic(objective, findings),
             rounds: opts.rounds ?? 1,

package/dist/config-catalog.d.ts

@@ -34,6 +34,23 @@ export interface ConfigCatalogSpec {
     readonly derivedDefaultNote?: string;
     readonly danger?: readonly CatalogDangerAxis[];
     readonly enumValues?: readonly string[];
+    /**
+     * S-201① —— 本行**回显**得出的词集(`enumValues` 的子集;缺席 ⇒ 与 `enumValues` 同集)。
+     *
+     * 🔴 `enumValues` 一直是**两义**的:它既是行对外宣告的「你可以写哪些词」([ref] 件⑤/⑧ 两条钉逐字锚
+     * 这一义:窄了=少宣告一档、宽了=宣告一个 boot 会拒的词),又被回显校验当成「实算值合不合法」的闭集。
+     * 两义在**多数**行上碰巧同集,于是差别只活在散文里 —— `MANUAL_MODE_SHELL_GATE` 的
+     * `derivedDefaultNote` 写着「真姿态只有 always/classify 两个」,`MODEL_DEFAULT_THINKING` 写着
+     * 「缺席/off ⇒ 不铸」,而**没有任何一条腿读那两句话**:`off` 照样留在回显闭集里,回显校验对它放行。
+     *
+     * ⇒ 把那半句散文变成一处**校验腿真读的声明**:`sanitizeEnumValue` 问 `echoWords ?? enumValues`,
+     * 于是「这一格的合法回显值」从此只有一个属主,不再靠人脑对两个词表做差集。
+     *
+     * 🔴 **不上 wire**:消费方(UI 下拉、非法值的纠错提示)要的是「可写集」= `enumValues`,那一义不变;
+     * 本字段服务的是服务端自己的回显纪律。一个词进得了 `enumValues` 却不在这里 ⇒ 它的语义恒是
+     * 「**缺席的另一种拼法**」(写下去与不写同效),那正是目前仅有的两行的形。
+     */
+    readonly echoWords?: readonly string[];
     /**
      * S-100 —— **底层布尔 ↔ 闭集词**的行内映射,只给「实算腿回布尔、而行对外说词」的 enum 行。
      *
@@ -91,7 +108,7 @@ export interface ConfigCatalogRow {
     readonly effectiveValue: CatalogValue;
     /**
      * S-100(additive;**只在真非法时铸,恒不铸 `false`**)—— 本行的实算值**落在它自己宣告的
-     * `enumValues` 之外**,或它的实算腿回了一个本行没有声明映射的布尔。
+     * 回显闭集之外**(`echoWords ?? enumValues`,S-201①),或它的实算腿回了一个本行没有声明映射的布尔。
      *
      * 在场时 `effectiveValue` 恒 `null`:回显一个集外值等于目录在教消费方写一个写回去就非法的词,
      * 而**静默丢**会让「配错了」与「真的没设」在 wire 上同形([ref] 响亮臂)。

package/dist/config-catalog.js

@@ -204,7 +204,7 @@ export const CONFIG_CATALOG = [
     r("LOG_LEVEL", "observability", "string", "日志档位", { staticDefault: "info", configKey: "logLevel" }),
     r("LSP_ENABLED", "orchestration", "boolean", "LSP 沙箱腿 opt-in(需烤好的 LSP 模板;host 腿另有 LSP_HOST_ENABLED)", { staticDefault: "false", configKey: "lspEnabled" }),
     r("LSP_HOST_ENABLED", "orchestration", "boolean", "LSP host 腿开关(本机 language server,优雅降级)", { staticDefault: "true", configKey: "lspHostEnabled" }),
-    r("MANUAL_MODE_SHELL_GATE", "approval", "enum", "手动模式 shell 门收紧腿(off=no-op 非放松 —— 本键只有收紧半场;拼错拒启)", { danger: SEC, enumValues: ["always", "classify", "off"], resolve: (c) => c.manualModeShellGate ?? null, derivedDefaultNote: "off/未设 ⇒ 本键不贡献任何东西(归一成键缺席)⇒ 回显 null;真姿态只有 always/classify 两个" }),
+    r("MANUAL_MODE_SHELL_GATE", "approval", "enum", "手动模式 shell 门收紧腿(off=no-op 非放松 —— 本键只有收紧半场;拼错拒启)", { danger: SEC, enumValues: ["always", "classify", "off"], echoWords: ["always", "classify"], resolve: (c) => c.manualModeShellGate ?? null, derivedDefaultNote: "off/未设 ⇒ 本键不贡献任何东西(归一成键缺席)⇒ 回显 null;真姿态只有 always/classify 两个" }),
     r("MAX_PRINCIPAL_COST_USD", "limitsHttp", "number", "per-principal 窗内成本天花板(0=关)", { staticDefault: "0", danger: BILL, configKey: "maxPrincipalCostUsd", center: cLimits("maxPrincipalCostUsd") }),
     r("MAX_TASK_COST_USD", "limitsHttp", "number", "单任务成本天花板(0=关)", { staticDefault: "0", danger: BILL, configKey: "maxTaskCostUsd", center: cLimits("maxTaskCostUsd") }),
     r("MAX_TASK_TOKENS", "limitsHttp", "number", "单任务 token 天花板(per-slice 窗;0=关)", { staticDefault: "0", danger: BILL, configKey: "maxTaskTokens", center: cLimits("maxTaskTokens") }),
@@ -270,7 +270,7 @@ export const CONFIG_CATALOG = [
     r("MODEL_COST_CACHE_WRITE", "modelPlane", "number", "主模型 cache-write 单价", { derivedDefaultNote: "四键全缺席 ⇒ 未定价(不铸 cost 键,成本读面缺席);任一设 ⇒ 四键在场,未设的按 0 显式", danger: BILL, resolve: (c) => c.model.cost?.cacheWrite ?? null, center: cModels("models[].cost.cacheWrite") }),
     r("MODEL_COST_INPUT", "modelPlane", "number", "主模型 input 单价(NaN 会让成本天花板整条消失 ⇒ 坏值拒启)", { derivedDefaultNote: "四键全缺席 ⇒ 未定价(不铸 cost 键,成本读面缺席);任一设 ⇒ 四键在场,未设的按 0 显式", danger: BILL, resolve: (c) => c.model.cost?.input ?? null, center: cModels("models[].cost.input") }),
     r("MODEL_COST_OUTPUT", "modelPlane", "number", "主模型 output 单价", { derivedDefaultNote: "四键全缺席 ⇒ 未定价(不铸 cost 键,成本读面缺席);任一设 ⇒ 四键在场,未设的按 0 显式", danger: BILL, resolve: (c) => c.model.cost?.output ?? null, center: cModels("models[].cost.output") }),
-    r("MODEL_DEFAULT_THINKING", "modelPlane", "enum", "主模型默认思考档(llm-core ThinkingLevel;off=不设模型级默认;未知词拒启)", { enumValues: ["minimal", "low", "medium", "high", "xhigh", "max", "off"], derivedDefaultNote: "缺席/off ⇒ 不铸 defaultThinking(逐任务档由 spec>role 决定)", resolve: (c) => c.model.defaultThinking ?? null }),
+    r("MODEL_DEFAULT_THINKING", "modelPlane", "enum", "主模型默认思考档(llm-core ThinkingLevel;off=不设模型级默认;未知词拒启)", { enumValues: ["minimal", "low", "medium", "high", "xhigh", "max", "off"], echoWords: ["minimal", "low", "medium", "high", "xhigh", "max"], derivedDefaultNote: "缺席/off ⇒ 不铸 defaultThinking(逐任务档由 spec>role 决定)", resolve: (c) => c.model.defaultThinking ?? null }),
     r("MODEL_DEGRADE_AT_COST_FRACTION", "modelPlane", "number", "预算降级触发比(spent/budget;>1=实际别降级)", { staticDefault: "0.7", danger: BILL }),
     r("MODEL_DEGRADE_ON", "modelPlane", "csv", "反应式降级触发词表(core DegradeReason 全集;拼错拒启)", { center: { domain: "models", path: "degrade", centerKey: "models", precedence: "center-wins", timing: "restart", restartSlice: "degrade-route" } }),
     r("MODEL_DEGRADE_REACTIVE", "modelPlane", "boolean", "反应式降级开关(degrade-route 重启片只在它开时活)", { staticDefault: "false", center: { domain: "models", path: "degrade", centerKey: "models", precedence: "center-wins", timing: "restart", restartSlice: "degrade-route" } }),
@@ -489,7 +489,7 @@ function stripUrlUserinfo(v) {
     return u.href;
 }
 function sanitizeEnumValue(spec, v) {
-    const words = spec.enumValues;
+    const words = spec.echoWords ?? spec.enumValues;
     if (v === null)
         return { value: null };
     if (words === undefined)

package/dist/config.js

@@ -1,4 +1,5 @@
 import { readFileSync } from "node:fs";
+import { DEFAULT_MODEL_REF } from "./model-select.js";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -872,14 +873,14 @@ function parseModelDomain() {
     const models = { default: model, [model.id]: model };
     if (cheapModel)
         models[cheapModel.id] = cheapModel;
-    const cheapRef = cheapModel ? cheapModel.id : "default";
+    const cheapRef = cheapModel ? cheapModel.id : DEFAULT_MODEL_REF;
     const verifierEnv = process.env.MODEL_VERIFIER;
-    const verifierRef = verifierEnv && models[verifierEnv] ? verifierEnv : "default";
+    const verifierRef = verifierEnv && models[verifierEnv] ? verifierEnv : DEFAULT_MODEL_REF;
     const roles = {
         verifier: verifierRef,
     };
     for (const r of ROSTER_PRIMARY_ROLES)
-        roles[r] = "default";
+        roles[r] = DEFAULT_MODEL_REF;
     for (const r of ROSTER_CHEAP_ROLES)
         roles[r] = cheapRef;
     for (const r of csv("MODEL_CODE_ROLES")) {

package/dist/env-facts.d.ts

@@ -96,6 +96,67 @@ export declare function acceptShellScratchpadDir(raw: unknown, opts: {
     hostSemanticsLane: boolean;
     warn: (msg: string, meta?: object) => void;
 }): Promise<string | undefined>;
+/**
+ * {@link acceptShellScratchpadDir} 的**词法半场**(S-351 拆出):零 I/O、可在请求的任何一点问。
+ *
+ * 为什么拆:S-351 的前判要在**任何副作用之前**回答「这条请求会把哪个目录当写门豁免域」,而验收门的
+ * 后半场是 `mkdir`(副作用 + I/O)。把判据抄一份到前判处 = 两份验收规则,而两份规则漂移的那天,前判
+ * 会替一条**根本不会被接受**的壳供路径拒掉请求(或反过来放过一条会被接受的)。所以规则只有这一份,
+ * 两个调用点各取所需:验收门 = 本函数 + mkdir;前判 = 本函数。
+ *
+ * 返回的是**词法归一后**(`resolve`)的拼法 —— 与验收门交给写门的那一个逐字相同。
+ */
+export declare function screenShellScratchpadDir(raw: unknown, opts: {
+    requirePrincipal: boolean;
+    hostSemanticsLane: boolean;
+    warn: (msg: string, meta?: object) => void;
+}): string | undefined;
+/**
+ * S-351(core 7.20.0 / [ref])—— **这条请求会不会把任务根放进写门的豁免域里**。
+ *
+ * ## 病形(引擎侧的硬拒,不是判决期的宽严)
+ * 写门的豁免域就是 scratchpad(`exemptDirs: [scratchpadDir]`,`task-settings.ts` 的
+ * `createFsWriteGatePolicy` 那一句),而门的根是这条 task 的 cwd。core 7.20.0 起,**豁免域等于根或是
+ * 根的祖先 ⇒ 构造期抛**(亲读安装树 `dist/core/fs-write-gate-policy.js:11-28`,
+ * `code = "config.write_exempt_dir_covers_root"`)——理由逐字:一条盖住根的豁免把根下**每一次写**都自动
+ * 批准,那就是整个工作区,门宁可拒绝被建出来,也不肯带着一扇静默关掉的写治理去跑。
+ *
+ * 本仓真正够得着这一形的只有**一条边**:调用方自设 `body.cwd` 进 scratchpad 树(server 自己**从不**
+ * 把 cwd 缺省到 scratchpad —— scratchpad 与 task root 是两棵子树)。它今天的下场是 spec 折叠期抛出一条
+ * 没人分诊过的错,而调用方看到的是一条与病因无关的 422。所以前判把它提前成一条**读得懂的请求拒绝**。
+ *
+ * ## 判据只有词法(不承诺 canonical)
+ * 引擎那一侧的构造期**没有 I/O**(同上坐标:`lexicalViewOf` 纯字符串),所以这里也只做词法 —— 承诺
+ * canonical 就是承诺一件此刻做不到的事(软链形的真身要到裁决时刻才问 fs,那是写门自己的第二道)。
+ *
+ * ## 射程(每一条都是「不这样写就会误拒」)
+ *  · **只在 cwd 真会被尊重时判**:`cwdHonored` 为假的部署(多租户 / 非 host 车道)把 cwd 直接忽略,
+ *    它永远不会变成门的根 —— 在那里拒等于凭空多一条 400;
+ *  · **豁免域取这条会话可能挂上的每一只**(不是「这一次挂哪只」):server 自算那条恒是候选(有 session
+ *    就算得出),壳供 `body.scratchpadDir` **过了词法验收**才追加为候选(过不了的那条永远挂不上,拿它拒
+ *    就是凭空多一条 400)。只判其一会留一条**跨请求**的洞:一条请求供一只合法壳 scratchpad 把判据引开、
+ *    同时把 cwd 指进自算那只,放行后 cwd 坐进会话表,下一条不带路径字段的请求回落自算形、死在引擎构造期,
+ *    而它根本没送过 cwd(codex r2 [medium] 实证);
+ *  · **`in-process` 车道(provider 未设)不在射程**:那条腿的门根是**进程自己的 cwd**,与请求字段无关 ——
+ *    对着一个请求字段拒一件不是它造成的事,是把诊断指向错的地方(如实登记,不假装覆盖)。
+ */
+export declare function scratchpadCoveringTaskRoot(args: {
+    cwd: unknown;
+    shellScratchpadDir: unknown;
+    localDataRoot: string;
+    sessionId: string | undefined;
+    requirePrincipal: boolean;
+    cwdHonored: boolean;
+}): {
+    cwd: {
+        asSpelled: string;
+        lexical: string;
+    };
+    scratchpadDir: {
+        asSpelled: string;
+        lexical: string;
+    };
+} | undefined;
 /** 删除一个 session 的 scratchpad 目录(rm -rf,幂等:目录不存在=no-op)。失败吞 warn 不抛——
  *  清理绝不 fault 调用它的 session-delete 路径;下一轮 {@link sweepStaleScratchpads} 仍会兜到它。 */
 export declare function purgeScratchpadDir(localDataRoot: string, sessionId: string): Promise<void>;

package/dist/env-facts.js

@@ -1,6 +1,7 @@
 import { isAbsolute, join, resolve, sep } from "node:path";
 import { mkdir, readdir, rm, stat } from "node:fs/promises";
 import { createHash } from "node:crypto";
+import { dirCoversPath, isValidCwd, normalizeAbsolutePathLexically } from "./task-cwd.js";
 const MAX_STR = 64;
 const MAX_CAPS = 16;
 const MAX_PATH = 160;
@@ -61,6 +62,19 @@ export async function ensureScratchpadDir(localDataRoot, sessionId) {
     }
 }
 export async function acceptShellScratchpadDir(raw, opts) {
+    const screened = screenShellScratchpadDir(raw, opts);
+    if (screened === undefined)
+        return undefined;
+    try {
+        await mkdir(screened, { recursive: true });
+        return screened;
+    }
+    catch (err) {
+        opts.warn("shell_scratchpad_ignored", { reason: "mkdir_failed", error: err instanceof Error ? err.message : String(err) });
+        return undefined;
+    }
+}
+export function screenShellScratchpadDir(raw, opts) {
     if (typeof raw !== "string" || raw.length === 0)
         return undefined;
     if (opts.requirePrincipal) {
@@ -85,14 +99,26 @@ export async function acceptShellScratchpadDir(raw, opts) {
         opts.warn("shell_scratchpad_ignored", { reason: "too_shallow", canonical });
         return undefined;
     }
-    try {
-        await mkdir(canonical, { recursive: true });
-        return canonical;
-    }
-    catch (err) {
-        opts.warn("shell_scratchpad_ignored", { reason: "mkdir_failed", error: err instanceof Error ? err.message : String(err) });
+    return canonical;
+}
+export function scratchpadCoveringTaskRoot(args) {
+    if (!args.cwdHonored || !isValidCwd(args.cwd))
         return undefined;
+    const candidates = [];
+    const shell = screenShellScratchpadDir(args.shellScratchpadDir, { requirePrincipal: args.requirePrincipal, hostSemanticsLane: true, warn: () => { } });
+    if (shell !== undefined)
+        candidates.push({ asSpelled: typeof args.shellScratchpadDir === "string" ? args.shellScratchpadDir : shell, dir: shell });
+    if (args.sessionId !== undefined) {
+        const own = scratchpadDirFor(args.localDataRoot, args.sessionId);
+        candidates.push({ asSpelled: own, dir: own });
     }
+    const hit = candidates.find((c) => dirCoversPath(c.dir, args.cwd));
+    if (hit === undefined)
+        return undefined;
+    return {
+        cwd: { asSpelled: args.cwd, lexical: normalizeAbsolutePathLexically(args.cwd) },
+        scratchpadDir: { asSpelled: hit.asSpelled, lexical: normalizeAbsolutePathLexically(hit.dir) },
+    };
 }
 export async function purgeScratchpadDir(localDataRoot, sessionId) {
     const dir = scratchpadDirFor(localDataRoot, sessionId);

package/dist/execution-lane-caps.d.ts

@@ -52,6 +52,18 @@ export interface ExecutionLaneCaps {
     /** core 的 `isRemoteExecutionEnv` 对本车道的判决(鸭子类型;判别位 = `config.remoteExec` 在不在场,
      *  **含 host**)。5.26.0 起它决定 `# Memory` 写指令撤不撤。 */
     readonly coreRemoteExecutionEnv: LaneCapability;
+    /**
+     * S-354 / core 7.20.0([ref]):这条车道的适配器**声明**了 `capabilities.canonicalPathAuthoritative`
+     * 没有 —— 即「我的 `canonicalPath` 是路径落点的权威,整链答不出来是解析器出了事,不是一个我看不见的
+     * 命名空间」。声明 ⇒ 读边界的执行期复核在解析器沉默时**拒**;缺席 ⇒ 今天每个适配器的读法(词法判决
+     * 成立、命令照跑)—— **缺席不是「声明为 false」**,所以这一位的 `unsupported` 读作「本车道没表态」。
+     *
+     * 判别式:各 adapter 的 `capabilities` 字面量(`plugins/remote-env-{host,ssh,adb,k8s,device,e2b,local-docker}.ts`),
+     * 由 core 的严格读器 `canonicalPathIsAuthoritative(env)` 读;对账测试逐 lane 拿**真 adapter 实例**问它。
+     * 本位存在的理由 = 让「新车道/新适配器不表态」变成**编译红**(穷举 switch 少一行即 tsc 红),而不是
+     * 静默继承一个没人表过态的缺席。
+     */
+    readonly canonicalPathAuthority: LaneCapability;
 }
 /**
  * per-lane 能力表。**穷举 switch,禁 default 臂**(hands-lane.ts:39-46 先例)。

package/dist/execution-lane-caps.js

@@ -19,6 +19,7 @@ export function executionLaneCaps(lane) {
                 memoryPersistenceCapable: NO,
                 hostFilePlane: YES,
                 coreRemoteExecutionEnv: NO,
+                canonicalPathAuthority: NO,
             };
         case "host":
             return {
@@ -35,6 +36,7 @@ export function executionLaneCaps(lane) {
                 memoryPersistenceCapable: YES,
                 hostFilePlane: YES,
                 coreRemoteExecutionEnv: YES,
+                canonicalPathAuthority: YES,
             };
         case "e2b":
             return {
@@ -51,6 +53,7 @@ export function executionLaneCaps(lane) {
                 memoryPersistenceCapable: NO,
                 hostFilePlane: NO,
                 coreRemoteExecutionEnv: YES,
+                canonicalPathAuthority: NO,
             };
         case "k8s":
             return {
@@ -67,6 +70,7 @@ export function executionLaneCaps(lane) {
                 memoryPersistenceCapable: NO,
                 hostFilePlane: NO,
                 coreRemoteExecutionEnv: YES,
+                canonicalPathAuthority: YES,
             };
         case "ssh":
             return {
@@ -83,6 +87,7 @@ export function executionLaneCaps(lane) {
                 memoryPersistenceCapable: NO,
                 hostFilePlane: NO,
                 coreRemoteExecutionEnv: YES,
+                canonicalPathAuthority: YES,
             };
         case "adb":
             return {
@@ -99,6 +104,7 @@ export function executionLaneCaps(lane) {
                 memoryPersistenceCapable: NO,
                 hostFilePlane: NO,
                 coreRemoteExecutionEnv: YES,
+                canonicalPathAuthority: YES,
             };
         case "local-docker":
             return {
@@ -115,6 +121,7 @@ export function executionLaneCaps(lane) {
                 memoryPersistenceCapable: NO,
                 hostFilePlane: NO,
                 coreRemoteExecutionEnv: YES,
+                canonicalPathAuthority: NO,
             };
         case "device":
             return {
@@ -131,6 +138,7 @@ export function executionLaneCaps(lane) {
                 memoryPersistenceCapable: NO,
                 hostFilePlane: NO,
                 coreRemoteExecutionEnv: YES,
+                canonicalPathAuthority: YES,
             };
     }
 }