@sema-agent/server 7.78.2 → 7.79.1

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";
@@ -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" });
@@ -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.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,
             };
     }
 }

package/dist/file-history-disclosure.d.ts

@@ -0,0 +1,53 @@
+/**
+ * S-157④ —— SQL file-history 店的 **typed 永久失败**披露座:散文一个铸点 + 机器面一只 sink。
+ *
+ * ## 病(基线 v7.79.0 逐行亲核 + 亲跑)
+ * `plugins/blob-backend.ts:55` 的 `BlobTooLargeError` 带 typed 判别码 `blob_too_large_for_sql`,头注
+ * 原话「绝不能与 transient 写失败混在一类(那类是可重试的 502;这类重试永远不会成功)」。可它一旦被
+ * `plugins/file-history-store-sql.ts` 的任何一条 `catch` 折进 `FileHistoryResult.error.message`,判别码
+ * 就只剩散文,**机器一位都读不到**。两条腿各自的后果:
+ *
+ * · **snapshot(边界捕获)腿**:引擎把失败包成一句散文交给 `RunnerDeps.onError({phase:"rewind"})`
+ *   (core 7.20.0 `dist/core/runner/prepare-file-history.js:269`/`:275`),服务那条臂从文本里抠**第一个**
+ *   括号词当 metric label —— 而第一个括号词恒是引擎自己的闭集码。实测:「这个文件永远存不进这口店」
+ *   与「连接被重置」在 `rewind_snapshot_failed_total` 上**同形** `code="snapshot_failed"`。
+ * · **trackEdit(首触备份)腿**:本服务用引擎默认的 `onTrackFailure:"refuse"`(`boot/runner-deps.ts` 亲读),
+ *   那条路 **完全不走 onError** —— 引擎把 `(track_failed: <本店 message>)` 念给模型,末句是
+ *   「Retry when the file-history store is healthy.」(`prepare-file-history.js:154`)。对这枚码那是永远
+ *   不会到来的一天,而**运维面一个计数都没有**:这条腿今天在遥测上完全不可见。
+ *
+ * ## 修法(源头留痕,不走文本通道)
+ * · **散文面**({@link discloseCaughtFailure} 的返回值):把 caught error 的 typed `code` 写成一个括号词
+ *   前置到它自己的 message 前 —— **不 `instanceof` 单挑任何一个类**(身上有字符串 `code` 就折),该店
+ *   11 处折点全部改走这一只函数。人与模型因此看得到「这是哪一类失败」。
+ * · **机器面**(同一只函数的副作用):码取自 typed 错**对象**、对闭集词表判定,**绝不从散文里抠**。
+ *   🔴 这一条是 codex R1-[high] 验真后的定形:文本通道**天然可伪造** —— 一个名叫
+ *   `(blob_too_large_for_sql).txt` 的文件读不出来时,它的路径就在 `snapshot_failed` 的散文里,任何
+ *   「从散文里取在册括号词」的读法都会把它当成一枚永久码(继而抑制掉真故障的告警)。闭集只约束基数,
+ *   不能证明来源。所以机读判定搬回**唯一知道真相的那一层**=铸错的地方,`rewind` 臂的读法一字不动。
+ * · 留痕三件套与 `observability/fail-open.ts` / `observability/secret-env-scrub.ts` 同律:**计数逐次**
+ *   (`file_history_permanent_failure_total{code}`)、**每进程每码一条 warn**(第二条起零新增内容,而
+ *   20G 树的用户每 turn 撞一次)、装配前累计的次数在 install 时补进 metrics。
+ */
+import type { Logger } from "./observability/logger.js";
+import type { Metrics } from "./observability/metrics.js";
+interface Sink {
+    logger?: Logger;
+    metrics?: Metrics;
+}
+/**
+ * 把一个 caught error 折进店侧散文,**并**在它是一枚 typed 永久失败时留痕。
+ *
+ * 返回值 = 散文形:带 typed `code` 的前缀一个括号词(`(blob_too_large_for_sql) blob of … exceeds …`),
+ * 不带的**逐字**是原 message(transient 失败的文案因此与本批之前一字不差)。
+ * 副作用 = 机器形:码取自错误对象,逐次计数 + 每进程每码一条 warn。观测绝不抛。
+ */
+export declare function discloseCaughtFailure(err: unknown): string;
+/** 装配层把 logger/metrics 接上(main.ts,与 `installFailOpenRecorder` 同一处)。 */
+export declare function installFileHistoryFailureRecorder(deps: Sink): void;
+/** 本进程逐码累计(测试/诊断读面)。 */
+export declare function fileHistoryPermanentFailureCounts(): ReadonlyMap<string, number>;
+/** 测试用重置(进程级状态在同一个 vitest worker 里跨用例存活)。 */
+export declare function resetFileHistoryFailureRecorderForTest(deps?: Sink): void;
+export {};
+//# sourceMappingURL=file-history-disclosure.d.ts.map

package/dist/file-history-disclosure.js

@@ -0,0 +1,89 @@
+const PERMANENT_STORE_FAILURE_CODES = {
+    blob_too_large_for_sql: {
+        note: "a blob is larger than this deployment's SQL snapshot-blob cap — the same file will fail every turn until the deployment changes",
+        knobs: "MINIO_ENDPOINT/MINIO_ACCESS_KEY/MINIO_SECRET_KEY (object storage) or SNAPSHOT_BLOB_SQL_MAX_BYTES (raise the cap)",
+    },
+};
+const PERMANENT_FAILURE_COUNTER = "file_history_permanent_failure_total";
+const PERMANENT_FAILURE_HELP = "file-history store failures whose typed code means retrying can NEVER succeed (the deployment must change), by code. " +
+    "Covers BOTH legs — the rewind boundary capture AND the first-touch trackEdit refusal, which the engine answers to the model " +
+    "without ever calling onError, so it appears in no other metric. Non-zero = go read the paired one-shot warn for the knobs.";
+let sink = {};
+let counts = new Map();
+let pushed = new Map();
+let warned = new Set();
+let pendingWarn = new Map();
+function isPermanentCode(code) {
+    return Object.prototype.hasOwnProperty.call(PERMANENT_STORE_FAILURE_CODES, code);
+}
+function drainToMetrics() {
+    const m = sink.metrics;
+    if (m === undefined)
+        return;
+    for (const [code, total] of counts) {
+        const already = pushed.get(code) ?? 0;
+        if (total > already) {
+            m.inc(PERMANENT_FAILURE_COUNTER, { code }, total - already);
+            pushed.set(code, total);
+        }
+    }
+}
+export function discloseCaughtFailure(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    const code = err?.code;
+    if (typeof code !== "string" || code === "")
+        return message;
+    if (isPermanentCode(code))
+        recordPermanent(code, message);
+    return `(${code}) ${message}`;
+}
+function safely(record) {
+    try {
+        record();
+    }
+    catch {
+    }
+}
+function recordPermanent(code, message) {
+    safely(() => {
+        counts.set(code, (counts.get(code) ?? 0) + 1);
+        drainToMetrics();
+        if (!warned.has(code))
+            emitFirstWarn(code, message);
+    });
+}
+function emitFirstWarn(code, message) {
+    if (!pendingWarn.has(code))
+        pendingWarn.set(code, message);
+    const logger = sink.logger;
+    if (logger === undefined)
+        return;
+    logger.warn("file_history_permanent_failure", {
+        code,
+        note: PERMANENT_STORE_FAILURE_CODES[code].note,
+        knobs: PERMANENT_STORE_FAILURE_CODES[code].knobs,
+        info: pendingWarn.get(code) ?? message,
+        once: "每进程每码一条;计数逐次,读 " + PERMANENT_FAILURE_COUNTER,
+    });
+    warned.add(code);
+    pendingWarn.delete(code);
+}
+export function installFileHistoryFailureRecorder(deps) {
+    sink = { ...deps };
+    deps.metrics?.counter(PERMANENT_FAILURE_COUNTER, PERMANENT_FAILURE_HELP);
+    drainToMetrics();
+    for (const [code, message] of [...pendingWarn])
+        safely(() => emitFirstWarn(code, message));
+}
+export function fileHistoryPermanentFailureCounts() {
+    return new Map(counts);
+}
+export function resetFileHistoryFailureRecorderForTest(deps = {}) {
+    counts = new Map();
+    pushed = new Map();
+    warned = new Set();
+    pendingWarn = new Map();
+    sink = { ...deps };
+    deps.metrics?.counter(PERMANENT_FAILURE_COUNTER, PERMANENT_FAILURE_HELP);
+}
+//# sourceMappingURL=file-history-disclosure.js.map

package/dist/http/admission.d.ts

@@ -0,0 +1,56 @@
+/**
+ * 提交准入(S-147 切片:`http/server.ts` 的 `prepareSpec` 与它的模块级校验词表逐字搬家,正文一字未改)。
+ * 读体 → 验型 → 授权 → 建 spec 的**唯一**一条链;tasks / runs / A2A 三个提交面共用它(抄一份 = 抄一份会漂的 400)。
+ * ctx 字段 3 只(`deps` / `readJson` / `runnerFor`),机器算(closure-free-vars)与手抄一致。
+ */
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { TaskRequestBody } from "./wire-types.js";
+import { HttpError } from "../security.js";
+import type { PreparedTaskSubmission, RouteHelpers } from "./route-ctx.js";
+import type { FlatServiceDeps } from "./server.js";
+/** = core `SKILL_CONTENT_MAX_CHARS`(1MB 加载门,core 1.293 起 invoke 全文零截断、超 1MB 整拒;常量在
+ *  dist/core/runner/synthetic-tools.js:84,未从 core 包根导出,故钉本地孪生+本出处注记)。修7 曾对齐旧
+ *  20k 截断门([ref] 飞轮考据:20k 是压缩保留区口径,invoke 时刻用错),core 1.293 撤门后本门跟随回收
+ *  ([ref]① 收口)——HTTP 面与引擎加载门同值,超限 400 fail-loud 而非引擎侧整拒后难诊断。
+ *
+ *  🔴 **这是技能面**唯一**剩下的尺寸门,而且它不是超集帽**:引擎在装配期对超 1 MiB 的技能本就整拒
+ *  (config 阶段错误),门上先答只是把同一个判决搬到调用方看得懂的地方。[ref] 退役的三条帽
+ *  (条数 / description / name 长度)都没有这个性质——它们是本仓自造的、CC 与引擎都没有的门。 */
+export declare const MAX_SKILL_CONTENT_CHARS = 1048576;
+export declare const MAX_SYSTEM_PROMPT_CHARS = 16384;
+/** Cap on a request's `outputSchema` (JSON-serialized) — an uncapped schema bloats the prompt + the per-turn
+ *  validation cost. 32KB comfortably holds a rich nested schema while bounding the abuse surface. */
+export declare const MAX_OUTPUT_SCHEMA_CHARS = 32768;
+/**
+ * Validate `body.skills` —— **形**校验 + 一条引擎孪生门。返回错误串(→ 400)或 null。
+ *
+ * 🔴 **[ref](7.77.0,硬 BREAKING;零别名零双读)**:此前这里有三条本仓自造的拒绝臂,全部退役 ——
+ *  · `at most 10 skills per request`(条数帽);
+ *  · `skill.description must be a string of at most 1024 characters`(描述长度帽);
+ *  · `skill.name must be a non-empty string of at most 64 characters` 里的 **长度**那一半。
+ *
+ * 退役的判据是**上游两侧都没有同形门**:CC 2.1.259 的技能清单渲染(`cli259.js:23195` 的预算算法)
+ * 在超预算时把**描述裁短**、再不够就退成 name-only,**从不**因为条数多或描述长而拒掉一条技能;
+ * 它的 `Ir()` 名字校验也只判非空 / 无配对代理 / 无首尾空白 / 无括号逗号控制字符,没有长度帽。
+ * 引擎侧同理:唯一整拒的是 1 MiB 的单技能加载门。于是那三条帽是「装了 11 个技能就 400」这种
+ * 纯本仓面的伤——收益是零(预算由渲染侧按字节兜),代价是用户装不进自己的技能库。
+ *
+ * **补偿**(三问的第三问):`settings.skillListingBudgetFraction` / `settings.skillListingMaxDescChars`
+ * 两个旋钮直达引擎的渲染预算(per-turn 成本的真属主)。
+ * ⚠️ **fraction 是**单向**的**:引擎的预算 = `min(窗口 × fraction, 8 000 字节)`,8 000 是**投递车道的结构
+ * 上限**(清单帧与同 turn 的其它附件共用一份完整送达额度)⇒ **调低生效、调高被夹**;调高唯一的用处是让
+ * 一个声明窗口小于 200 000 token 的模型把清单预算拿回大窗口的水平。别把这句读成「调用方可以随便加大」。
+ * 体积面照旧由**非技能专属**的 8 MiB 请求体上限兜住(`MAX_BODY`),那是一条一直都在的门。
+ *
+ * 🔴 **server 侧禁裁列表 / 禁截描述**:渲染归引擎(单一属主)。本函数只判「这一条技能的形能不能用」。
+ */
+export declare function validateUserSkills(skills: unknown): string | null;
+export declare function createAdmission(ctx: {
+    deps: FlatServiceDeps;
+    runnerFor: NonNullable<FlatServiceDeps["runnerFor"]>;
+} & Pick<RouteHelpers, "readJson">): {
+    prepareSpec: (req: IncomingMessage, res: ServerResponse, bodyIn?: TaskRequestBody, onTypedFailure?: (err: HttpError) => void, legFacts?: {
+        liveStream?: boolean;
+    }) => Promise<PreparedTaskSubmission | null>;
+};
+//# sourceMappingURL=admission.d.ts.map