@sema-agent/server 7.134.0 → 7.136.0

package/dist/capabilities/scenarios.d.ts

@@ -2,7 +2,7 @@ import { type WebFetchConfig, type BackgroundAgentStore, type CheckpointStore, t
 import type { Logger } from "../observability/logger.js";
 import { type SubagentExtraToolSet } from "./builtin-tools.js";
 import { type RepoReadClient } from "./repo-tools.js";
-import { type LoadedSkill } from "./skills.js";
+import { type LoadedSkill, type ScenarioSkillEntry } from "./skills.js";
 import { type ScenarioHands } from "./hands-lane.js";
 import type { DelegationRootWitness } from "../delegated-session-owner.js";
 /**
@@ -28,7 +28,7 @@ export interface ScenarioBundle {
      */
     hands: ScenarioHands;
     /**
-     * S-1376:本场景从 roster 里**真卸载**的工具名(`TaskSpec.excludeTools`:per-scenario 的 roster 移除,schema 不进 `tools[]`;不是策略 deny)。缺席 = 不卸。
+     * [ref]:本场景从 roster 里**真卸载**的工具名(`TaskSpec.excludeTools`:per-scenario 的 roster 移除,schema 不进 `tools[]`;不是策略 deny)。缺席 = 不卸。
      * 经 {@link buildExcludeToolsSeat} 与调用方自己的 `excludeTools` 取并后写进 `TaskSpec`(HTTP 腿与 run-local 腿同一只写点)—— 场景只能多卸,调用方也只能多卸。
      * 与 `hands` 正交:`hands: "none"` 是整只手不挂(scan / code-review),本键是挂手之后卸掉其中一部分(cowork 卸编码类工具、留文件读)。
      */
@@ -83,7 +83,7 @@ export interface ScenarioContext {
      */
     sessionId?: string;
     /**
-     * S-1770 / S-1808:**委派树根的见证**(停驻挂点的属主来源)—— 根会话 id + 调用方判断那一刻读到的根行住客(`delegated-session-owner.ts` 的 `DelegationRootWitness`)。
+     * [ref] / [ref]:**委派树根的见证**(停驻挂点的属主来源)—— 根会话 id + 调用方判断那一刻读到的根行住客(`delegated-session-owner.ts` 的 `DelegationRootWitness`)。
      * 由**每一个**接了停驻挂点的取用方显式交出(一条读法,没有回落):请求腿 = 本请求经鉴权解析的会话与受理时那一读(`boot/resolve-spec.ts`);`/decide` 赎回面 = 行上的
      * `rootSessionId` 与赎回腿 claim 前后两读的那一位住客(`parked-revive-surface.ts`,交不交座都交)。它**只**喂停驻挂点,不挂任何会话级设施(那是 {@link sessionId} 的事,
      * 判据是「这只 bundle 是不是在那只会话上取用的」,与属主来源是两个独立判据)。缺席 = 没有根可交(boot 期探针、run-local、行上没有根)⇒ 律给哨兵。
@@ -104,7 +104,7 @@ export interface ScenarioDeps {
      *  could exfil via an arbitrary public URL; the SSRF floor only blocks internal). Single-user TOC keeps WebFetch. */
     requirePrincipal?: boolean;
     /**
-     * S-1652:这台部署的执行车道**有没有手**(`laneWiresExecutionEnv`;`REMOTE_EXEC` 未设 = `in-process` = 没有)。场景详情读面据它与场景自己的 `hands` 表态一起答
+     * [ref]:这台部署的执行车道**有没有手**(`laneWiresExecutionEnv`;`REMOTE_EXEC` 未设 = `in-process` = 没有)。场景详情读面据它与场景自己的 `hands` 表态一起答
      * 「这个场景的 run 有没有工作区」({@link runHasWorkspace}),进而给出附件可受理供给集。**缺席按没有手读**(宁少说不多说:不广告一个会撞 400 的 `path`)。
      */
     handsLane?: boolean;
@@ -123,7 +123,7 @@ export interface ScenarioDeps {
      * execute-time late-bound via ctx.taskId → TaskEnvRegistry, so ONE spec serves every spawn) cannot ride the
      * ASSEMBLY-time static `subagent.tools` pool; core evaluates the factory at each spawn and merges its product into the
      * pool, then it goes through core's `resolveToolSubset` whitelist like any other tool (agent-def allowTools/denyTools
-     * still govern — no extra gate needed on our side). A SET, not a bare factory (core 7.46.0 #1432): its `tools` are both
+     * still govern — no extra gate needed on our side). A SET, not a bare factory (core 7.46.0 [ref]): its `tools` are both
      * what a spawn can be handed and the roster the delegation tool declares (`extraToolNames`), so the factory cannot hand
      * out a tool the roster does not name. Absent ⇒ the delegation tool injects `Now` alone.
      */
@@ -152,7 +152,7 @@ export interface ScenarioDeps {
      */
     checkpointStore?: CheckpointStore;
     /**
-     * S-1770:比 core 挂点多一个参数 —— `root` = **委派树根的见证,由取用这只 bundle 的调用方交出**({@link ScenarioContext.delegationRoot};缺席 = 没有根可交)。
+     * [ref]:比 core 挂点多一个参数 —— `root` = **委派树根的见证,由取用这只 bundle 的调用方交出**({@link ScenarioContext.delegationRoot};缺席 = 没有根可交)。
      * core 的挂点只给子代 id,停驻写下 / 定夺的宿主行属主却要按委派继承律取委派树根的属主;场景工厂把见证绑进交给 core 的那只闭包,同一棵树里任何深度的后台子代
      * 停驻都经它(子代沿用父的委派工具实例)。
      */
@@ -217,12 +217,18 @@ export interface ScenarioDetail {
     /** 机读原因键;仅 `available:false` 时在场(缺席=没有理由)。消费方按键分支,禁匹配英文文案。 */
     unavailableReason?: ScenarioUnavailableReason;
     /**
-     * S-1652:**这个场景在本部署上受理的附件供给**(顶层能力位 `userAttachments.supplies` 的子集,保持席位序;键恒在场,不是 `null`)。
+     * [ref]:**这个场景在本部署上受理的附件供给**(顶层能力位 `userAttachments.supplies` 的子集,保持席位序;键恒在场,不是 `null`)。
      * 顶层能力位说的是引擎席位**能承载**的三种供给(常量);`path` 读的是这一 run 的工作区,只有「场景挂手 ∧ 部署的执行车道有手」的 run 才有
      * (判官 {@link runHasWorkspace}),其余整条 `path` 条目由引擎 prepare 拒 `config.user_attachment_invalid` —— 宿主发之前读这一格,不靠撞 400。
      * `content_text` / `content_image` 与工作区无关,恒在。
      */
     attachmentSupplies: UserAttachmentSupplyWord[];
+    /**
+     * [ref]:**这个场景交进每一个 run 的部署技能**(本部署技能目录 + 配置源交来的;不含请求体自带的 `skills`)—— 名字 / 描述 / 来处,不带正文。
+     * 与工厂交进 `TaskSpec` 的那一份是**同一只过滤**(技能范围 + `skills.ts` 的 `skillsInScope`)的两个投影:同一组、同一个序。名字就是 `userInvokedSkills` 点名用的串。
+     * 键恒在场;没有技能 ⇒ `[]`。
+     */
+    skills: ScenarioSkillEntry[];
 }
 /** 引擎附件席位的供给词(`USER_ATTACHMENT_SEAT.supplies` 的成员;取型,不手抄)。 */
 export type UserAttachmentSupplyWord = (typeof USER_ATTACHMENT_SEAT)["supplies"][number];
@@ -249,14 +255,26 @@ export declare const BUILTIN_SCENARIO_HANDS: {
     readonly scan: "none";
     readonly cowork: "full";
 };
+/**
+ * [ref]:内建场景的**技能范围**(技能 `scenarios` 标签按哪个名字匹配)—— **全仓唯一声明处**:各场景工厂交进 `TaskSpec` 的技能与场景卡上的技能清单都按这张表取范围,
+ * 再过同一只过滤(`skills.ts` 的 `skillsInScope`),两边因此恒为同一组技能。按 {@link BuiltinScenarioName} 键控 ⇒ 加 / 删一个内建场景而这里没跟 = 编译红。
+ * `code` 的范围是 `default`:它与 default 共用一只工厂(工具 / 技能面恒等由构造保证),打了 `scenarios: code` 的技能不进 code 的 run。center 场景的范围是它自己的名字。
+ */
+export declare const BUILTIN_SCENARIO_SKILL_SCOPE: {
+    readonly code: "default";
+    readonly default: "default";
+    readonly "code-review": "code-review";
+    readonly scan: "scan";
+    readonly cowork: "cowork";
+};
 /**
  * `branded` = 这台部署是不是品牌部署 —— 部署座挂品牌行读的同一只判官(`brand-identity.ts` `isBrandedDeployment`)交进来;没有默认值:每个调用点说出这件事实。
  * 品牌部署上,品牌行 `when.binding` 那张表里的场景(`BRAND_IDENTITY_SCENARIOS`)的 `promptSummary` 点名 Sema 产品身份 —— 读面说的就是模型收到的。
  */
-export declare function builtinScenarioDetails(scenarios: Record<string, Scenario>, deps: Pick<ScenarioDeps, "repoClient" | "handsLane">, branded: boolean): Record<string, ScenarioDetail>;
+export declare function builtinScenarioDetails(scenarios: Record<string, Scenario>, deps: Pick<ScenarioDeps, "repoClient" | "handsLane" | "skills">, branded: boolean): Record<string, ScenarioDetail>;
 /** center 条目详情(有效性判定与 centerScenarios 完全同款:无效条目既不进 overlay 也不进详情——
  *  保证约定①「详情显示的来源=运行实际用的定义」永不错位)。 */
-export declare function centerScenarioDetails(specs: CenterScenarioSpec[] | undefined, builtinNames: string[], deps: Pick<ScenarioDeps, "repoClient" | "handsLane">): Record<string, ScenarioDetail>;
+export declare function centerScenarioDetails(specs: CenterScenarioSpec[] | undefined, builtinNames: string[], deps: Pick<ScenarioDeps, "repoClient" | "handsLane" | "skills">): Record<string, ScenarioDetail>;
 export interface CenterScenarioSpec {
     name: string;
     toolset: string;
@@ -300,7 +318,7 @@ export declare function centerScenarios(deps: ScenarioDeps, specs: CenterScenari
  * Personalization seam: merge the caller's own skills AFTER the scenario's, with
  * SCENARIO-WINS on a name clash — the scenario / center skills own the name (they are the deployment's baseline
  * wording, not an enforcement face: permissions / write gates / hooks do not ride on skills, and a caller may
- * unload the whole set with `disableSkills`, S-946); user content never shadows them. Duplicate names within the user list keep the first. Clashes are logged for audit
+ * unload the whole set with `disableSkills`, [ref]); user content never shadows them. Duplicate names within the user list keep the first. Clashes are logged for audit
  * (silent drops would make "my skill didn't fire" undebuggable). Input is already shape/size-validated
  * by the HTTP layer (validateUserSkills); this stays pure merge policy.
  */

package/dist/capabilities/scenarios.js

@@ -4,7 +4,7 @@ import { createSubagentExtraTools, extraToolsErrorFields, nowTool } from "./buil
 import { parseRepo, repoToolsFor } from "./repo-tools.js";
 import { NOW_TOOL_NAME, REPO_PULL_DIFF_TOOL_NAME, REPO_READ_FILE_TOOL_NAME, REPO_TREE_TOOL_NAME } from "./host-tool-names.js";
 import { createWebSearchBackend, judgeRequestWebSearch } from "../plugins/web-search.js";
-import { skillsForScenario } from "./skills.js";
+import { scenarioSkillEntries, skillsForScenario } from "./skills.js";
 import { OFFICE_EXCLUDED_TOOL_NAMES, runHasWorkspace } from "./hands-lane.js";
 import { BRAND_IDENTITY_SCENARIOS } from "./brand-identity.js";
 export function buildPromptSeats(scenarioName, prompt, callerSystemPrompt) {
@@ -69,7 +69,7 @@ export function buildScenarios(deps) {
                 }).filter((t) => t.name !== WEB_FETCH_TOOL_NAME || deps.requirePrincipal !== true),
             ],
             hands: BUILTIN_SCENARIO_HANDS.default,
-            skills: skillsForScenario(deps.skills, "default"),
+            skills: skillsForScenario(deps.skills, BUILTIN_SCENARIO_SKILL_SCOPE.default),
         };
     };
     return {
@@ -77,6 +77,7 @@ export function buildScenarios(deps) {
         code: (req, principal, ctx) => ({
             ...defaultScenario(req, principal, ctx),
             hands: BUILTIN_SCENARIO_HANDS.code,
+            skills: skillsForScenario(deps.skills, BUILTIN_SCENARIO_SKILL_SCOPE.code),
             prompt: { role: "code" },
         }),
         "code-review": (req) => codeReview(deps, req),
@@ -88,13 +89,13 @@ export function buildScenarios(deps) {
             return {
                 tools: [...repoToolsFor(repoClient, parseRepo(req.repo)), nowTool()],
                 hands: BUILTIN_SCENARIO_HANDS.scan,
-                skills: skillsForScenario(deps.skills, "scan"),
+                skills: skillsForScenario(deps.skills, BUILTIN_SCENARIO_SKILL_SCOPE.scan),
             };
         },
         cowork: (req, principal, ctx) => ({
             ...defaultScenario(req, principal, ctx),
             hands: BUILTIN_SCENARIO_HANDS.cowork,
-            skills: skillsForScenario(deps.skills, "cowork"),
+            skills: skillsForScenario(deps.skills, BUILTIN_SCENARIO_SKILL_SCOPE.cowork),
             excludeTools: OFFICE_EXCLUDED_TOOL_NAMES,
             prompt: { role: "cowork" },
         }),
@@ -124,6 +125,13 @@ export const BUILTIN_SCENARIO_HANDS = {
     scan: "none",
     cowork: "full",
 };
+export const BUILTIN_SCENARIO_SKILL_SCOPE = {
+    code: "default",
+    default: "default",
+    "code-review": "code-review",
+    scan: "scan",
+    cowork: "cowork",
+};
 export function builtinScenarioDetails(scenarios, deps, branded) {
     const probe = (name, req, principal, fallback) => {
         try {
@@ -138,6 +146,7 @@ export function builtinScenarioDetails(scenarios, deps, branded) {
         name, source: "builtin", builtin: true, summary, toolset, tools, promptSummary, enabled: true,
         ...availabilityFields(deps, toolset),
         attachmentSupplies: attachmentSuppliesFor(BUILTIN_SCENARIO_HANDS[name], deps.handsLane === true),
+        skills: scenarioSkillEntries(deps.skills, BUILTIN_SCENARIO_SKILL_SCOPE[name]),
     });
     const brandedScenario = (name) => branded && BRAND_IDENTITY_SCENARIOS.includes(name);
     const details = {
@@ -170,6 +179,7 @@ export function centerScenarioDetails(specs, builtinNames, deps) {
             enabled: true,
             ...availabilityFields(deps, spec.toolset),
             attachmentSupplies: attachmentSuppliesFor(toolset.hands, deps.handsLane === true),
+            skills: scenarioSkillEntries(deps.skills, spec.name),
         };
     }
     return out;
@@ -244,7 +254,7 @@ function codeReview(deps, req) {
     }
     const coords = parseRepo(req.repo);
     const repoTools = repoToolsFor(repoClient, coords);
-    const skills = skillsForScenario(deps.skills, "code-review");
+    const skills = skillsForScenario(deps.skills, BUILTIN_SCENARIO_SKILL_SCOPE["code-review"]);
     const hands = BUILTIN_SCENARIO_HANDS["code-review"];
     return { tools: [...repoTools, nowTool()], hands, skills, prompt: { roleText: REVIEWER_ROLE_TEXT } };
 }

package/dist/capabilities/send-user-file-tool.d.ts

@@ -53,7 +53,7 @@ export declare function sendUserFileTool(deps: {
  * posture (their denyTools sets predate this tool, so core's resolveToolSubset would let it through). `ctx.agentType`
  * carries the spawned definition's name (core subagent.js); membership in core's builtin catalog ⇒ inject nothing.
  *
- * 🔴 S-1058(7.116.0):修前这里还有一道 **F1 部署策略预判** —— 部署审批面(`APPROVAL_DENY` / `REQUIRE` / `NEVER_AUTO`)点名 SendUserFile 就一只都
+ * 🔴 [ref](7.116.0):修前这里还有一道 **F1 部署策略预判** —— 部署审批面(`APPROVAL_DENY` / `REQUIRE` / `NEVER_AUTO`)点名 SendUserFile 就一只都
  * 不注入,前提是「subRunner 不带策略、core 的子代不继承父的 toolPolicy」(core 1.287 时的事实)。core 自 7.40.1 起顶层 run 解析后的调用方策略
  * (`spec.toolPolicy ?? deps.toolPolicy`)与它冻结的审批席经继承链(`InheritedGate.parentConstraints`)判子代的注入工具:deny ⇒ 零执行;ask ⇒ 顶层
  * 审批席被问一次;无审批席 ⇒ 拒(core 7.41.0 钉)。本仓在真实装配上亲跑十格(spec / deps 两槽 × deny / ask 允 / ask 拒 / 无审批席 / 耐久车道无活席,

package/dist/capabilities/skills.d.ts

@@ -36,8 +36,16 @@ export interface LoadedSkill {
     spec: SkillSpec;
     /** Scenarios this skill applies to; empty = global (every scenario). */
     scenarios: string[];
+    /**
+     * [ref] —— 这只技能的**来处**,由铸它的那条装载腿写下(唯一写点;之后谁都不改写,只投影):`factory` = 本部署的技能目录(`SKILLS_DIR`,{@link loadDeploymentSkills});
+     * `center` = 本部署的配置源交来的(中心 / 本地 `config.d` 的技能清单 `applySkillsManifest`,或配置声明的插件 `applyCenterPlugins`)。配置源按名盖掉出厂同名技能 ⇒ 盖上来的那只是 `center`。
+     * 场景卡的技能清单原样投这一位(`GET /v1/capabilities/scenarios/:name` 的 `skills[].source`)。
+     */
+    source: SkillSource;
 }
-/** 加载 lane 的信任级。缺席(受控 lane:烤制进镜像的 skills 目录)= 维持既有语义,symlink 照跟
+/** 技能来处的闭集(见 {@link LoadedSkill.source})。 */
+export type SkillSource = "factory" | "center";
+/** 加载 lane 的事实:来处(`source`,必填)与信任级。`confineTo` 缺席(受控 lane:烤制进镜像的 skills 目录)= 维持既有语义,symlink 照跟
  *  ——那个便利是有意的(`foo.md -> 共享文件`)。`confineTo` 在场(**不可信 lane**:第三方 git checkout,
  *  见 center-plugins 的 plugin 装载)= 每个被读条目 realpath 后必须仍在该根之内,逃逸即抛。
  *  🔴 为什么信任级必须是**参数**而不是注释里的假设:本函数的头注原写着「skills dir 全受控」,而
@@ -45,12 +53,13 @@ export interface LoadedSkill {
  *  于是 checkout 里某个 skill 条目(`任意 .md -> /宿主/任意文件`)会被读进 spec.files 进入提示词。resolvePluginSkillsRoot
  *  只 realpath 守了 skills **根**,根下逐条目没守。 */
 export interface LoadSkillsOptions {
+    /** [ref]:这条装载腿铸出的技能的来处({@link LoadedSkill.source})—— **必填**:装载器自己判断不了它读的是哪一种目录,由调用的那条腿说出这件事实。 */
+    source: SkillSource;
     /** 不可信 lane 的约束根(通常=clone root)。缺席=受控 lane,不做逐条目约束。 */
     confineTo?: string;
     /**
-     * S-377 —— 「**工具跑的那台机器**的盘就是本进程这台盘吗」。真 ⇒ 目录形态技能带上自己的目录
-     * (`SkillSpec.baseDir`);假/缺席 ⇒ **不带**。判据的单一属主 = `task-cwd.ts` 的
-     * {@link import("../task-cwd.js").toolsRunOnThisHost}(调用方按它算,别在这里第二次判 lane)。
+     * [ref] —— 「**工具跑的那台机器**的盘就是本进程这台盘吗」。真 ⇒ 目录形态技能带上自己的目录
+     * (`SkillSpec.baseDir`);假/缺席 ⇒ **不带**。判据的单一属主 = 部署形表行 `toolsOnThisHost`(`deployment-shape.ts`;调用方按它算,别在这里第二次判 lane)。
      *
      * 🔴 **缺席 = 不带**,是**故意的 fail-closed 方向**:带了一条工具那边不存在的路径,伤是「模型按它去
      * 读、扑空,顺带看到本机目录布局」;不带的伤只是少一条线索(附件本来就随 invoke 全文内联投递,
@@ -64,13 +73,13 @@ export interface LoadSkillsOptions {
  *  `/a/root` 前缀。目标不存在 ⇒ realpath 抛 ENOENT,同样是拒绝(悬空链接不该被读)。
  *  `label` = 错误文本里的对象名(center-plugins 用它约束 manifest 本体,报错不该指成 skill entry)。 */
 export declare function assertConfined(p: string, rootReal: string, label?: string): void;
-export declare function loadSkills(dir: string, opts?: LoadSkillsOptions): LoadedSkill[];
+export declare function loadSkills(dir: string, opts: LoadSkillsOptions): LoadedSkill[];
 /**
- * S-602 —— **出厂技能**的装载腿(`SKILLS_DIR` 自扫)。stage-07 与 run-local 两处装配点**都调这一只**:改前两处
- * 各写一遍 `loadSkills(config.skillsDir, { toolsShareThisFilesystem: toolsRunOnThisHost(config) })`,测试只能
+ * [ref] —— **出厂技能**的装载腿(`SKILLS_DIR` 自扫)。stage-07 与 run-local 两处装配点**都调这一只**:改前两处
+ * 各写一遍 `loadSkills(config.skillsDir, { toolsShareThisFilesystem: <车道判据>(config) })`,测试只能
  * 直传布尔去证 `loadSkills`(`baked-skills.test.ts`),证不到「config → 装配腿 → baseDir」这一段;收成一只
- * 之后,联合格从 config 走到 `baseDir`(`test/capabilities-http.test.ts` S-602 段)证的就是两处装配点本人。
- * 判据属主不变:`task-cwd.ts` 的 {@link toolsRunOnThisHost}(S-602 起 in-process ⇒ 假 ⇒ 目录形技能不带 `baseDir`)。
+ * 之后,联合格从 config 走到 `baseDir`(`test/capabilities-http.test.ts` [ref] 段)证的就是两处装配点本人。
+ * 判据属主:部署形表行 `toolsOnThisHost`([ref];[ref] 起 in-process ⇒ 假 ⇒ 目录形技能不带 `baseDir`)。
  */
 export declare function loadDeploymentSkills(config: {
     readonly skillsDir: string;
@@ -78,9 +87,19 @@ export declare function loadDeploymentSkills(config: {
         readonly provider: RemoteExecProvider;
     } | undefined;
 }, logger?: Logger): LoadedSkill[];
-/** Skills applicable to a scenario: those tagged with it, plus untagged (global) ones.
- *  [ref]:alias 窗撤销,单键查询——退役旧名标签不再命中(迁移面在 7.44 发车帖/MIGRATION 记载)。 */
-export declare function skillsForScenario(loaded: LoadedSkill[], scenario: string): SkillSpec[];
+/** 一个技能范围交进 `TaskSpec` 的技能(场景工厂的 `skills`)。范围从哪来见 `scenarios.ts` 的 `BUILTIN_SCENARIO_SKILL_SCOPE`(center 场景 = 它自己的名字)。 */
+export declare function skillsForScenario(loaded: readonly LoadedSkill[], scope: string): SkillSpec[];
+/**
+ * [ref] —— 场景卡技能清单的一条(`GET /v1/capabilities/scenarios/:name` 的 `skills[]`):名字 / 描述 / 来处,**不带正文**,也不带技能上的两只工具清单
+ * (`allowedTools` / `disallowedTools`)。名字就是提交体 `userInvokedSkills` 点名时用的那个串。
+ */
+export interface ScenarioSkillEntry {
+    readonly name: string;
+    readonly description: string;
+    readonly source: SkillSource;
+}
+/** 一个技能范围的卡上清单 —— 与 {@link skillsForScenario} 同一只过滤、同一个序,只是投影不同。 */
+export declare function scenarioSkillEntries(loaded: readonly LoadedSkill[], scope: string): ScenarioSkillEntry[];
 /** {@link parseFrontmatter} 的三种读数(闭集):`absent` = 第一行不是围栏,没有 frontmatter(正当的全局技能)· `block` = 围栏收好了的块 · `unclosed` = 第一行是围栏而块没收好(读不了 —— 调用方拒载)。 */
 export type FrontmatterRead = {
     readonly kind: "absent";

package/dist/capabilities/skills.js

@@ -1,6 +1,6 @@
 import { readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { join, resolve, sep } from "node:path";
-import { toolsRunOnThisHost } from "../task-cwd.js";
+import { DEPLOYMENT_SHAPE_PREDICATES } from "../deployment-shape.js";
 import { createLogger } from "../observability/logger.js";
 export function assertConfined(p, rootReal, label = "skill entry") {
     let real;
@@ -15,7 +15,7 @@ export function assertConfined(p, rootReal, label = "skill entry") {
     }
 }
 export function loadSkills(dir, opts) {
-    const logger = opts?.logger ?? createLogger("warn");
+    const logger = opts.logger ?? createLogger("warn");
     let entries;
     try {
         entries = readdirSync(dir, { withFileTypes: true });
@@ -25,15 +25,15 @@ export function loadSkills(dir, opts) {
     }
     const out = [];
     const seen = new Map();
-    const push = (skill, source) => {
+    const push = (skill, file) => {
         const prior = seen.get(skill.spec.name);
         if (prior !== undefined) {
-            throw new Error(`duplicate skill name "${skill.spec.name}": ${prior} vs ${source}`);
+            throw new Error(`duplicate skill name "${skill.spec.name}": ${prior} vs ${file}`);
         }
-        seen.set(skill.spec.name, source);
+        seen.set(skill.spec.name, file);
         out.push(skill);
     };
-    const confineRoot = opts?.confineTo !== undefined ? realpathSync(opts.confineTo) : undefined;
+    const confineRoot = opts.confineTo !== undefined ? realpathSync(opts.confineTo) : undefined;
     const isFileLike = (entry, p) => entry.isFile() || (entry.isSymbolicLink() && statSync(p).isFile());
     const isDirLike = (entry, p) => entry.isDirectory() || (entry.isSymbolicLink() && statSync(p).isDirectory());
     for (const entry of entries.slice().sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))) {
@@ -43,10 +43,10 @@ export function loadSkills(dir, opts) {
             if (confineRoot !== undefined)
                 assertConfined(join(dir, entry.name), confineRoot);
             const raw = readFileSync(join(dir, entry.name), "utf8");
-            const source = join(dir, entry.name);
-            const parsed = parseSkill(raw, entry.name.replace(/\.md$/, ""), source, logger);
+            const file = join(dir, entry.name);
+            const parsed = parseSkill(raw, entry.name.replace(/\.md$/, ""), file, opts.source, logger);
             if (parsed !== undefined)
-                push(parsed, source);
+                push(parsed, file);
         }
         else if (isDirLike(entry, join(dir, entry.name))) {
             const skillDir = join(dir, entry.name);
@@ -61,13 +61,13 @@ export function loadSkills(dir, opts) {
             }
             if (confineRoot !== undefined)
                 assertConfined(join(skillDir, "SKILL.md"), confineRoot);
-            const skill = parseSkill(raw, entry.name, join(skillDir, "SKILL.md"), logger);
+            const skill = parseSkill(raw, entry.name, join(skillDir, "SKILL.md"), opts.source, logger);
             if (skill === undefined)
                 continue;
             const files = collectAttachments(skillDir, "", confineRoot);
             if (files.length > 0)
                 skill.spec.files = files;
-            if (opts?.toolsShareThisFilesystem === true)
+            if (opts.toolsShareThisFilesystem === true)
                 skill.spec.baseDir = resolve(skillDir);
             push(skill, join(skillDir, "SKILL.md"));
         }
@@ -75,7 +75,7 @@ export function loadSkills(dir, opts) {
     return out;
 }
 export function loadDeploymentSkills(config, logger) {
-    return loadSkills(config.skillsDir, { toolsShareThisFilesystem: toolsRunOnThisHost(config), ...(logger !== undefined ? { logger } : {}) });
+    return loadSkills(config.skillsDir, { source: "factory", toolsShareThisFilesystem: DEPLOYMENT_SHAPE_PREDICATES.toolsOnThisHost.holds(config), ...(logger !== undefined ? { logger } : {}) });
 }
 function collectAttachments(skillDir, rel, confineRoot) {
     const files = [];
@@ -100,12 +100,12 @@ function collectAttachments(skillDir, rel, confineRoot) {
     }
     return files;
 }
-function parseSkill(raw, fallbackName, source, logger) {
+function parseSkill(raw, fallbackName, file, origin, logger) {
     const fm = parseFrontmatter(raw);
     if (fm.kind === "unclosed") {
         logger.warn("skill_refused", {
             skill: fallbackName,
-            source,
+            source: file,
             reason: "frontmatter_unclosed",
             note: "the file opens a frontmatter fence (`---`) that is never closed, so its `scenarios` restriction cannot be read — this skill is NOT loaded (it is not demoted to a global skill); close the fence or remove the opening line",
         });
@@ -119,10 +119,16 @@ function parseSkill(raw, fallbackName, source, logger) {
         .split(",")
         .map((s) => s.trim())
         .filter(Boolean);
-    return { spec: { name, description, content: body.trim() }, scenarios };
+    return { spec: { name, description, content: body.trim() }, scenarios, source: origin };
 }
-export function skillsForScenario(loaded, scenario) {
-    return loaded.filter((k) => k.scenarios.length === 0 || k.scenarios.includes(scenario)).map((k) => k.spec);
+function skillsInScope(loaded, scope) {
+    return loaded.filter((k) => k.scenarios.length === 0 || k.scenarios.includes(scope));
+}
+export function skillsForScenario(loaded, scope) {
+    return skillsInScope(loaded, scope).map((k) => k.spec);
+}
+export function scenarioSkillEntries(loaded, scope) {
+    return skillsInScope(loaded, scope).map((k) => ({ name: k.spec.name, description: k.spec.description, source: k.source }));
 }
 const FRONTMATTER_OPENS_RE = /^---[ \t]*\r?(?:\n|$)/;
 const FRONTMATTER_BLOCK_RE = /^---[ \t]*\r?\n(?:---[ \t]*\r?(?:\n|$)|([\s\S]*?)\r?\n---[ \t]*\r?(?:\n|$))([\s\S]*)$/;

package/dist/capabilities/tool-defer.d.ts

@@ -19,7 +19,7 @@
  *    🔴 该判断在 core 5.40.0 / 7.15.0 上**逐字仍成立**(亲验):两次收窄动的都是「候选集是谁」,而
  *    Agent / Task 四件是 **caller spec 工具**,收窄后照样在候选池里 —— 不开 auto 的理由没有被消解。
  *    我方**从不接线**这个座:全树零 `RunnerDeps.deferMode` 赋值(web-admin 曾有同形近名 `deferModelPlane`,
- *    与本轴无关,已于 S-668 波 0 退役)。机器钉见 test/tool-defer.test.ts 的 [ref] 件⑤ 格 —— 这条「零接线」正是本仓
+ *    与本轴无关,已于 [ref] 波 0 退役)。机器钉见 test/tool-defer.test.ts 的 [ref] 件⑤ 格 —— 这条「零接线」正是本仓
  *    在两个 core 世代之间行为逐字不变的**全部**依据,所以它值一根钉而不只是一句注。
  *  - per-tool `ToolSpec.defer:true` 是本 helper 施加的那一位。**7.15.0 起它是一次「进候选集」的声明,
  *    不再是「一定占位」的保证** —— 长尾集单独一只(下面实测 ≈842 字符)远在阈值之下,于是这根旋钮在

package/dist/capability-facts.d.ts

@@ -23,6 +23,7 @@ import type { ServiceConfig } from "./config.js";
 import type { OwnerAwareSessionStore } from "./security.js";
 import type { ServiceFileHistoryStore } from "./plugins/store-backend.js";
 import { resolveStreamApprovalGate, type ApprovalFrameFamily } from "./tool-approval.js";
+import { type SyncBlobHistoryStore } from "./session-sync.js";
 import { type WorkspaceSyncCapability } from "./workspace-space.js";
 import type { WorkspaceCacheCapability } from "./workspace-cache.js";
 /** why 闭集:词 → 给运维看的一句义(诊断 / 测试读它;wire 上的拒句由各门自写)。 */
@@ -31,14 +32,13 @@ export declare const CAPABILITY_FACT_WHY: {
     readonly subagent_registry_absent: "the sub-agent steer registry is not wired";
     readonly subagent_output_face_absent: "the background sub-agent output face is not wired";
     readonly task_handle_faces_absent: "the background task-handle output/stop faces are not wired";
-    readonly session_owner_face_absent: "the session store has no ownership face (sessionStorage.ownerOf)";
+    readonly session_head_face_absent: "the session store has no by-id head read (sessionStorage.headOf — owner, occupant and leaf of a session row in one read)";
     readonly checkpoint_store_absent: "no durable checkpoint store is wired (DURABLE_APPROVAL)";
     readonly session_audit_absent: "no session audit view is wired (needs a durable session store)";
     readonly session_watch_absent: "the session watch registry is not wired";
-    readonly session_leaf_face_absent: "the session store has no leaf-read face (sessionStorage.getLeafId)";
     readonly session_lister_absent: "no session enumerator is wired (session store or run store listSessions)";
     readonly session_fork_face_absent: "the session store has no fork face";
-    readonly session_row_faces_absent: "the session store has no session-row faces (sessionFaceOf / sessionSummaryOf / patchSessionMeta)";
+    readonly session_row_faces_absent: "the session store has no session-row faces (headOf / sessionSummaryOf / patchSessionMeta)";
     readonly session_purge_absent: "no session purge coordinator is wired";
     readonly session_policy_store_absent: "no session policy store is wired";
     readonly store_backend_absent: "no store backend is wired (DB_BACKEND=memory, multi-tenant bare boot, or half-configured SQL)";
@@ -121,48 +121,50 @@ export declare function taskHandles(d: Pick<Deps, "runStore" | "taskHandleOutput
     output: Store<"taskHandleOutput">;
     stop: Store<"taskHandleStop">;
 }>;
-type OwnedSessionStore = WithMethods<OwnerAwareSessionStore, "ownerOf">;
-/** 会话属主面在场(入站 owner 门的地基;缺它,带会话的门一律 fail-closed)。 */
-export declare function sessionOwnership(d: Pick<Deps, "sessionStorage">): Fact<"session_owner_face_absent", {
-    sessionStorage: OwnedSessionStore;
+/** 会话店按 id 读一行的唯一读口在场(core `headOf`:属主 / 住客 / 叶子一次读;「有没有」与 `session-incarnation.ts` 的 `headReadOf` 同判)。 */
+type HeadReadingSessionStore = WithMethods<OwnerAwareSessionStore, "headOf">;
+/** 会话属主面在场(入站 owner 门的地基;缺它,带会话的门一律 fail-closed)。属主 = `headOf(id)?.owner`。 */
+export declare function sessionOwnership(d: Pick<Deps, "sessionStorage">): Fact<"session_head_face_absent", {
+    sessionStorage: HeadReadingSessionStore;
 }>;
-export declare function mcpReconnect(d: Pick<Deps, "runStore" | "sessionStorage">): Fact<"run_store_absent" | "session_owner_face_absent", {
+export declare function mcpReconnect(d: Pick<Deps, "runStore" | "sessionStorage">): Fact<"run_store_absent" | "session_head_face_absent", {
     runStore: Store<"runStore">;
-    sessionStorage: OwnedSessionStore;
+    sessionStorage: HeadReadingSessionStore;
 }>;
 export declare function sessionAuditView(d: Pick<Deps, "sessionAudit">): Fact<"session_audit_absent", {
     sessionAudit: Store<"sessionAudit">;
 }>;
-export declare function sessionEventStream(d: Pick<Deps, "sessionWatch" | "sessionStorage">): Fact<"session_watch_absent" | "session_leaf_face_absent" | "session_owner_face_absent", {
+/** 会话 SSE(watch 注册表 ∧ 头读:属主门与叶子都是 `headOf` 的投影)。 */
+export declare function sessionEventStream(d: Pick<Deps, "sessionWatch" | "sessionStorage">): Fact<"session_watch_absent" | "session_head_face_absent", {
     watch: Store<"sessionWatch">;
-    sessionStorage: WithMethods<OwnerAwareSessionStore, "ownerOf" | "getLeafId">;
+    sessionStorage: HeadReadingSessionStore;
 }>;
 type SessionLister = NonNullable<OwnerAwareSessionStore["listSessions"]>;
 /** 会话枚举面:session 店的 `listSessions`,否则老形 run 店聚合。见证 = 已绑好宿主的那一只。 */
 export declare function sessionList(d: Pick<Deps, "sessionStorage" | "runStore">): Fact<"session_lister_absent", {
     lister: SessionLister;
 }>;
-export declare function sessionFork(d: Pick<Deps, "sessionStorage">): Fact<"session_fork_face_absent" | "session_owner_face_absent", {
-    sessionStorage: WithMethods<OwnerAwareSessionStore, "ownerOf" | "fork">;
+export declare function sessionFork(d: Pick<Deps, "sessionStorage">): Fact<"session_fork_face_absent" | "session_head_face_absent", {
+    sessionStorage: WithMethods<OwnerAwareSessionStore, "headOf" | "fork">;
 }>;
-/** 会话行可写位(`PATCH /v1/sessions/:id`):会话店的会话面(属主 + 化身一次读 —— 门判属主、写与读回按化身条件)∧ 行写口(写后按同一住客读回)。
- *  三只 durable 店(SQL 双生 / local)都带;内存 dev 店没有 ⇒ 501。
+/** 会话行可写位(`PATCH /v1/sessions/:id`):会话店的头读(属主 + 化身一次读 —— 门判属主、写与读回按化身条件)∧ 行写口(写后按同一住客读回)。
+ *  三只 durable 店(SQL 双生 / local)都带;内存 dev 店没有行写口 ⇒ 501。
  *  本面**没有**独立能力位(契约附录 B.2c 登记):老 worker 对这一动词答 405,本事实为假的部署答 501。 */
 export declare function sessionPatch(d: Pick<Deps, "sessionStorage">): Fact<"session_row_faces_absent", {
-    sessionStorage: WithMethods<OwnerAwareSessionStore, "sessionFaceOf" | "patchSessionMeta">;
+    sessionStorage: WithMethods<OwnerAwareSessionStore, "headOf" | "patchSessionMeta">;
 }>;
-export declare function sessionDelete(d: Pick<Deps, "purgeSession" | "sessionStorage">): Fact<"session_purge_absent" | "session_owner_face_absent", {
+export declare function sessionDelete(d: Pick<Deps, "purgeSession" | "sessionStorage">): Fact<"session_purge_absent" | "session_head_face_absent", {
     purge: Store<"purgeSession">;
-    sessionStorage: OwnedSessionStore;
+    sessionStorage: HeadReadingSessionStore;
 }>;
-export declare function sessionPolicy(d: Pick<Deps, "sessionPolicyStore" | "sessionStorage">): Fact<"session_policy_store_absent" | "session_owner_face_absent", {
+export declare function sessionPolicy(d: Pick<Deps, "sessionPolicyStore" | "sessionStorage">): Fact<"session_policy_store_absent" | "session_head_face_absent", {
     policyStore: Store<"sessionPolicyStore">;
-    sessionStorage: OwnedSessionStore;
+    sessionStorage: HeadReadingSessionStore;
 }>;
-type SyncSessionStore = WithMethods<OwnerAwareSessionStore, "exportEntries" | "exportEntriesStream" | "beginImportStaging" | "sessionFaceOf" | "sessionSummaryOf" | "patchSessionMeta">;
+type SyncSessionStore = WithMethods<OwnerAwareSessionStore, "exportEntries" | "exportEntriesStream" | "beginImportStaging" | "headOf" | "sessionSummaryOf" | "patchSessionMeta">;
 type SessionSyncWhy = "store_backend_absent" | "file_history_store_absent" | "session_export_absent" | "session_import_staging_absent" | "session_row_faces_absent" | "policy_purge_absent";
 /** 会话对等同步的**对话半族**(manifest / entries / plan / import 两相):后端 ∧ 文件历史店 ∧ 导出两面 ∧ staged 导入面 ∧
- *  会话行三口(门读会话面 —— 属主 + 化身一次读,属主判门、化身给 identical 短路腿;manifest 带 `title` / `pinned`;导入经唯一写口按导入落定的
+ *  会话行三口(门读头 `headOf` —— 属主 + 化身一次读,属主判门、化身给 identical 短路腿;manifest 带 `title` / `pinned`;导入经唯一写口按导入落定的
  *  那一位住客重放它们)∧ policy 店能清(overwrite-dst 的 commit 要擦目的端旧 policy 行)。
  *  文件历史的 blob 搬运是另一只事实。 */
 export declare function sessionSync(d: Pick<Deps, "backend" | "sessionStorage" | "fileHistoryStore" | "sessionPolicyStore">): Fact<SessionSyncWhy, {
@@ -170,13 +172,8 @@ export declare function sessionSync(d: Pick<Deps, "backend" | "sessionStorage" |
     sessionStorage: SyncSessionStore;
     historyStore: ServiceFileHistoryStore;
 }>;
-/** blob 两面齐备的文件历史店(marker 门,不做名字探测:local 的引擎文件店带一只同名私有助手)。 */
-export type SyncBlobHistoryStore = ServiceFileHistoryStore & {
-    readonly syncBlobFaces: true;
-} & {
-    [P in "putBlob" | "getBlob"]-?: NonNullable<ServiceFileHistoryStore[P]>;
-};
-/** 会话同步的**文件历史半族**:对话半族 ∧ 文件历史店有 blob 搬运面(只有 SQL 两只店有)。 */
+/** 会话同步的**文件历史半族**:对话半族 ∧ 文件历史店有 blob 搬运面(只有 SQL 两只店有)。「店有没有 blob 两面」只在 `syncBlobFacesOf` 判一次(marker 门,不做名字探测),
+ *  blob 取值口 `blobGetterOf` 读的是同一只 —— 本事实为真 ⟺ 取值口通到 `historyStore.getBlob`。 */
 export declare function sessionSyncFileHistory(d: Pick<Deps, "backend" | "sessionStorage" | "fileHistoryStore" | "sessionPolicyStore">): Fact<SessionSyncWhy | "sync_blob_faces_absent", {
     historyStore: SyncBlobHistoryStore;
 }>;
@@ -205,7 +202,7 @@ export declare function streamApproval(d: Pick<Deps, "toolApproval" | "config" |
  * 读根授权(「Yes, and add directory」)这台部署**受理不受理** —— `GET /v1/capabilities` 的 `approvalReadRootGrant` 位,与
  * `POST /v1/tool-approvals/:id/respond` 对应答体 `readRootGrant` 的受理门**读同一只**(位说不受理而口照收,就是「位说 X、行为不是 X」)。
  *
- * 判据 = 单用户 host 车道姿态 {@link cwdHonored}(与调用方 `cwd` / 附加目录同一条信任边界):授权把一个**宿主目录**加进本 run 的读目录,
+ * 判据 = 部署形表行 `callerOwnsWorkerDisk`(手在本 worker 盘上 ∧ 单主;与调用方附加目录同一条信任边界):授权把一个**宿主目录**加进本 run 的读目录,
  * 只有「这台机器一个可信主人」的姿态才有这个授权的语义;多租户与云上 / 容器车道的读面另有归宿(沙箱内的读面档位见 `READ_FACE`)。
  * 消费方的选项可见条件是**合取**:卡上有 `readRootCandidate`(逐卡位,引擎铸)∧ 本位为真。位缺席 = 老 server(不受理)。
  * 没有别的端点按本位判可用与否 —— 它只管应答体里的这一键。
@@ -220,7 +217,7 @@ export declare function readRootGrant(d: Pick<Deps, "config">): Fact<"read_root_
  *  · 活卡协调器缺席 ⇒ `[]`(没有审批卡可呈)。
  * 对 why 闭集穷举:`streamApproval` 的拒因多一个 ⇒ 这里编译红,逼着给新拒因定族。三条执行腿选族读的是同一只判据的 `active`,
  * 与本映射的「在场 ⇒ 呈卡族」是同一条规则(真腿对拍钉在 `test/stream-approval-on-e2e.test.ts`)。没有端点按它拒:它是消费方分派帧族的读点,`streamApproval` 的词义不变。
- * S-1914:它也是壳**声明**的依据 —— 一条 run 只在 `settings.approvalFrameFamilies` 含本位那一个族时有活审批通道(三条腿判的是同一只映射
+ * [ref]:它也是壳**声明**的依据 —— 一条 run 只在 `settings.approvalFrameFamilies` 含本位那一个族时有活审批通道(三条腿判的是同一只映射
  * `presentedApprovalFrameFamily`);不含 ⇒ 这条腿不呈卡,问当场交无人值守政策口。本位的值不因声明而变。
  */
 export declare function approvalFrameFamilies(stream: ReturnType<typeof streamApproval>): readonly ApprovalFrameFamily[];
@@ -341,7 +338,7 @@ export declare function workflowsJournal(d: Pick<Deps, "workflowRunStore" | "wor
  * `workspace-space.ts`;`persist` 缺省 `space`,`off` = 每轮新建)。**唯一读法**:能力位 `workspaceSync` 投影它的见证,k8s 适配器工厂(`boot/execution-env.ts`)把同一份
  * 见证交给适配器(适配器自己不再解析策略)。`persist: "off"` 仍是 available(存储在、没开 —— 缺省或运维显式 off)—— 与缺席不同义。
  *
- * **为何只读配置仍恒真**:`space` 的空间按会话住客分区、按 run 店的一行提交 —— 住客只有一只按 id 读(会话店的 `incarnationOf`,
+ * **为何只读配置仍恒真**:`space` 的空间按会话住客分区、按 run 店的一行提交 —— 住客只有一只按 id 读(会话店的 `headOf`,
  * 会话行上的那一格),行住在存储后端里。缺一的组合在起服时就被拒(`boot/execution-env.ts` 的 `assertWorkspaceSpaceReadable`,装配第 5 段,
  * 读的正是本事实的见证)⇒ 凡是起得来、报 `space` 的部署都读得出住客、写得下行,本事实不需要运行期依赖(再加一位 = 同一前提两处判)。
  * 剩下的「这条 run 读不到住客」是逐 run 的读失败(适配器的 `unavailable` 臂,响亮一行),不是部署形。