@sema-agent/server 1.323.0 → 2.0.1

package/dist/capabilities/center-plugins.js

@@ -1,16 +1,41 @@
+/**
+ * plugins 域 worker 消费半场(契约冻结 board [1361]②/[1362] 四收紧/[1366]①;2026-07-28 开工车)。
+ *
+ * center 只存"插件从哪来"(PluginSpec 引用,永不承载可执行字节);worker 半场 = 把引用物化成本地
+ * 目录并把其中的 **skills** 装进 baseline(v1 装载面;commands 由 cli 壳消费——board [1363] 即 cli
+ * 答的命令契约稿,worker 侧本无命令面,这是分工不是降级)。挂 applyCenterSkills 同 reconcile 周期
+ * (boot 期,buildScenarios 之前)。
+ *
+ * 契约条款落点(与 test/center-plugins.test.ts 逐条对应):
+ *  - https-only + `PLUGINS_ALLOW_HOSTS`(缺省 github.com):{@link validatePluginDecl}。registry-core
+ *    0.10.23 已在 schema 层单真源拒非 https,worker 侧**仍复验**——纵深:wire 可能来自旧 center。
+ *  - sha 全 40hex + checkout 强制:{@link gitClonePlan}(有 sha = init+fetch-by-sha+checkout,不信
+ *    分支名也不拉全史;无 sha = `--depth 1` HEAD)。
+ *  - clone 姿势隔离:GIT_CONFIG_GLOBAL/SYSTEM=/dev/null + GIT_TERMINAL_PROMPT=0(无凭据仓 fail 而非
+ *    挂交互 prompt)。私仓凭据走各机自己的 credential helper,永不入声明。
+ *  - manifest 路径逃逸(../ /绝对路径/symlink 出根)= 整条拒装:{@link resolvePluginSkillsRoot}
+ *    (realpath 后前缀判定)。
+ *  - 撞名让位(收紧④):plugin 的 skill 与 baseline(builtin/center 直发)同名 ⇒ **plugin 让位**
+ *    (跳过+letGo 留痕)。⚠️ 方向与 applyCenterSkills 的 center-wins 相反——center 直发 skills 过了
+ *    publisher RBAC+发布审批,plugin 内容只是 git 仓字节,信任级不同,让位方向因此相反。
+ *  - fail-loud 单条不连坐 + LKG(上次成功物化留盘,拉取失败沿用):{@link applyCenterPlugins}。
+ */
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { promises as fsp, realpathSync, existsSync, readFileSync } from "node:fs";
 import { join, resolve, isAbsolute, sep } from "node:path";
 import { loadSkills } from "./skills.js";
 const execFileP = promisify(execFile);
+/** 缺省 clone host 白名单(契约条款 1;国内镜像走本名单加 https 镜像域,不开 http 口)。 */
 export const DEFAULT_PLUGIN_ALLOW_HOSTS = ["github.com"];
+/** 条款 1/2/4:https-only、host 全等白名单、sha 40hex。纯函数,worker 侧纵深复验(不信任 wire 已验过)。 */
 export function validatePluginDecl(decl, allowHosts) {
     const name = typeof decl.name === "string" && decl.name !== "" ? decl.name : "(unnamed)";
     if (decl.enabled === false)
         return { ok: false, skip: true, name, reason: "enabled:false" };
     const kind = decl.source?.kind;
     if (kind === "marketplace") {
+        // v1 暂缓:marketplace 物化(add-by-url + install-by-name)是 v2 面;skip 不连坐,warn 留痕。
         return { ok: false, skip: true, name, reason: "marketplace source: not materialized in v1 (skills lane ships git-form first)" };
     }
     if (kind !== "git")
@@ -26,6 +51,7 @@ export function validatePluginDecl(decl, allowHosts) {
     catch {
         return { ok: false, name, reason: "https url does not parse" };
     }
+    // host 全等匹配——evil-github.com / github.com.evil.io 都不隐含放行。
     if (!allowHosts.some((h) => h.toLowerCase() === host)) {
         return { ok: false, name, reason: `host ${host} not in PLUGINS_ALLOW_HOSTS (default github.com; extend with a comma-separated https mirror domain list)` };
     }
@@ -37,15 +63,17 @@ export function validatePluginDecl(decl, allowHosts) {
     }
     return { ok: true, name, url };
 }
+/** 条款 3/5:clone 计划(argv 序列 + 隔离 env)。纯数据,让"姿势"可被钉死。 */
 export function gitClonePlan(o) {
     const env = {
-        GIT_CONFIG_GLOBAL: "/dev/null",
+        GIT_CONFIG_GLOBAL: "/dev/null", // 收紧③:宿主 git 配置(insteadOf/credential/hooks)一概不继承
         GIT_CONFIG_SYSTEM: "/dev/null",
-        GIT_TERMINAL_PROMPT: "0",
+        GIT_TERMINAL_PROMPT: "0", // 无凭据仓 ⇒ fail-loud,绝不挂在交互 prompt 上
     };
     if (o.sha === undefined) {
         return { steps: [["clone", "--depth", "1", "--quiet", o.url, o.dest]], env };
     }
+    // 有 sha:init + fetch-by-sha + checkout —— 不信分支名、不拉全史;fetch 不到该 sha = 该条失败。
     return {
         steps: [
             ["init", "--quiet", o.dest],
@@ -55,6 +83,9 @@ export function gitClonePlan(o) {
         env,
     };
 }
+/** 条款 5 的 manifest 半场:`.claude-plugin/plugin.json` 的 `skillsPath`(缺省 `skills/`;cli plugin
+ *  布局同族)。返回 ok:true+dir:undefined = 插件没有 skills 目录(可以只有 commands——那是 cli 壳的
+ *  半场,worker 装 0 个 skill 不算失败);ok:false = 路径逃逸,整条拒装。 */
 export function resolvePluginSkillsRoot(cloneRoot) {
     let skillsPath = "skills";
     try {
@@ -63,22 +94,27 @@ export function resolvePluginSkillsRoot(cloneRoot) {
             skillsPath = manifest.skillsPath;
     }
     catch {
+        /* 无 manifest / 坏 JSON ⇒ 缺省 skills/(manifest 是可选面) */
     }
     if (isAbsolute(skillsPath))
         return { ok: false, reason: `skillsPath must be relative (got ${skillsPath})` };
     const rootReal = realpathSync(cloneRoot);
     const candidate = resolve(rootReal, skillsPath);
+    // 先做词法前缀判定(../ 逃逸在 realpath 之前就拒——目标可能不存在)
     if (candidate !== rootReal && !candidate.startsWith(rootReal + sep)) {
         return { ok: false, reason: `skillsPath escapes the plugin root (${skillsPath})` };
     }
     if (!existsSync(candidate))
         return { ok: true };
+    // symlink 出根:对存在的目标 realpath 再判一次
     const real = realpathSync(candidate);
     if (real !== rootReal && !real.startsWith(rootReal + sep)) {
         return { ok: false, reason: `skillsPath resolves outside the plugin root via symlink (${skillsPath})` };
     }
     return { ok: true, dir: candidate };
 }
+/** 总入口(条款 3/7/8):逐条物化 + 装载 + 让位合并。materialize 盘位 = `<cacheRoot>/<name>/live`
+ *  (成功后原子 rename 替换,失败保留旧盘位 = LKG)。 */
 export async function applyCenterPlugins(baseline, eff, opts) {
     const declared = Array.isArray(eff.plugins)
         ? (eff.plugins)
@@ -91,7 +127,7 @@ export async function applyCenterPlugins(baseline, eff, opts) {
     const runGit = opts.runGit ?? (async (args, env) => {
         await execFileP("git", args, { env: { ...process.env, ...env }, timeout: 120_000, maxBuffer: 4 * 1024 * 1024 });
     });
-    const taken = new Set(baseline.map((s) => s.spec.name));
+    const taken = new Set(baseline.map((s) => s.spec.name)); // 让位判据:baseline(builtin+center 直发)恒赢
     for (const decl of declared) {
         const v = opts.skipValidate
             ? { ok: true, name: String(decl.name), url: String(decl.source?.url), ...(typeof decl.sha === "string" ? { sha: decl.sha } : {}) }
@@ -106,12 +142,14 @@ export async function applyCenterPlugins(baseline, eff, opts) {
             continue;
         }
         const liveDir = join(opts.cacheRoot, v.name, "live");
+        // ── 物化:clone 到 staging,成功后原子替换 live;失败保留旧 live = LKG ──
         const staging = join(opts.cacheRoot, v.name, `staging-${process.pid}`);
         let materialized = false;
         try {
             await fsp.rm(staging, { recursive: true, force: true });
             await fsp.mkdir(staging, { recursive: true });
             const plan = gitClonePlan({ url: v.url, dest: staging, sha: v.sha });
+            // clone 目标目录已建:单步 clone 允许空目录;init 形对空目录同样成立。
             for (const step of plan.steps)
                 await runGit(step, plan.env);
             await fsp.rm(liveDir, { recursive: true, force: true });
@@ -122,6 +160,7 @@ export async function applyCenterPlugins(baseline, eff, opts) {
         catch (err) {
             await fsp.rm(staging, { recursive: true, force: true }).catch(() => undefined);
             if (existsSync(liveDir)) {
+                // LKG:拉取失败沿用上次成功物化(applyCenterSkills 同款语义)。
                 opts.logger?.warn("center_plugin_fetch_failed_lkg", { plugin: v.name, error: err instanceof Error ? err.message : String(err) });
                 out.lkgUsed.push(v.name);
             }
@@ -131,6 +170,7 @@ export async function applyCenterPlugins(baseline, eff, opts) {
                 continue;
             }
         }
+        // ── 装载:skills 目录(路径逃逸=整条拒装;fail-loud 单条不连坐)──
         try {
             const rootCheck = resolvePluginSkillsRoot(liveDir);
             if (!rootCheck.ok) {
@@ -139,10 +179,11 @@ export async function applyCenterPlugins(baseline, eff, opts) {
                 continue;
             }
             if (!rootCheck.dir)
-                continue;
+                continue; // 无 skills 目录:合法(commands-only 插件,cli 壳的半场)
             const loaded = loadSkills(rootCheck.dir);
             for (const skill of loaded) {
                 if (taken.has(skill.spec.name)) {
+                    // 收紧④:plugin 让位(方向与 center-wins 相反,理由见模块顶注)。
                     out.letGo.push({ plugin: v.name, skill: skill.spec.name });
                     opts.logger?.warn("center_plugin_skill_shadowed", { plugin: v.name, skill: skill.spec.name, note: "name taken by builtin/center skill — plugin yields (contract tightening-4)" });
                     continue;

package/dist/capabilities/center-prompts.d.ts

@@ -1,6 +1,34 @@
+/**
+ * center prompts 消费投影腿([1043]④/[1050]③ 分工:web 承存储+covering 解析+下发,server 承本模块;
+ * [1057] 下发形定稿 / [1061] registry-core 0.10.16 schema / [1062]⑤「server 零新义务=逐字透传」)。
+ *
+ * 链路:center(sema-web)把 covering 走完的**基线终形**经 `GET /api/config/effective` 的 additive
+ * `prompts` key 下发 → 本模块按任务 scenario 选包(`scenarioOverrides[s] ?? sections`,整包替换非增量,
+ * [1057]①c)→ 声明数组**逐字**(含 opt-in `contentHash`,core 1.315 校验+manifest 透传)喂 core 既有
+ * typed `stableBlocks` 钩子。守卫全在 core(id 规范/slot 闭集/core/ 命名空间拒绝/identity 三锚
+ * pass-through/锁定槽不可写)——server 不做语义复检([1057]①f:identity 完整角色层由 center 编辑面把关)。
+ *
+ * 仅有的一层「形校验」不是语义复检,是**防炸底线**(详见其现居所 `src/prompts-domain-validate.ts`——
+ * 判形半场已下沉到该中立叶子,本文件 re-export 保兼容;design/158 S6,lens2 §G):core 对坏形声明的
+ * 守卫是 THROW(assemble 期),server 在采用前做结构判形,坏形=拒绝采用该候选的 prompts 面。
+ *
+ * 生效语义(两段史):1.222 时 core 1.315 的 epoch 是 bundled-only(声明不进 descriptor),热换=resume
+ * 三失真,故临时 restart-to-apply;core 1.316([1068] 裁 a/[1070]d)把声明以 (id,slot,chars,contentHash?)
+ * 纳入 artifactDigest——声明变=digest 变=**下任务边界自动重 pin**(既有 legacy_migration 机制接手),
+ * 进行中会话 epoch pin 保稳。自此恢复**热采用**(main.ts boot+refresh 双点 adopt),与 center
+ * 「发布=新任务生效」产品语义对齐([1051]②b)。字节级检测只认 opt-in contentHash(文本不进 digest,
+ * 防会话可导出面字典预映)——center 链路恒逐 section 铸([1065]),本投影逐字透传即全强度。
+ */
 import { type PromptProvider, type PublishedPromptArtifactEnvelope } from "@sema-agent/core";
 import { type EffectiveCenterPrompts, type PromptsDomainFaces } from "../prompts-domain-validate.js";
+/** 判形半场(validateCenterPrompts/validatePromptsDomain/CORE_ENGINE_VERSION 及两 interface)已下沉到
+ *  中立叶子 `src/prompts-domain-validate.ts`(design/158 S6,lens2 §G:消 config-lkg → capabilities 的
+ *  唯一分层反向边)。此处 re-export 保兼容——既有消费者(main/run-local/测试)零改动。 */
 export { validateCenterPrompts, validatePromptsDomain, CORE_ENGINE_VERSION, type EffectiveCenterPrompts, type PromptsDomainFaces } from "../prompts-domain-validate.js";
+/** [985]b / [1285] — §9.4 by-digest 补拉组合店:local miss ⇒ fetchRaw(digest) 从 center 拉 envelope ⇒
+ *  core verifyPromptArtifact 全管线 + **回验「拿到的=要的」digest 逐位**(center 答非所问=丢弃)⇒
+ *  best-effort 回写 inner(下次直命中)。任何失败=undefined(诚实缺席,fail-loud 归 core 的
+ *  prompt_snapshot_unavailable——绝不拼杂交)。 */
 export declare function withPromptArtifactBackfill(inner: {
     get(d: string, o: {
         engineVersion: string;
@@ -10,6 +38,11 @@ export declare function withPromptArtifactBackfill(inner: {
     info: (msg: string, meta?: Record<string, unknown>) => void;
     warn: (msg: string, meta?: Record<string, unknown>) => void;
 }): typeof inner;
+/** e/b 接线([1236]① seam/[985]e):catalog 轴的两态过渡推进 core 的 CenterPromptSource——
+ *  present(且身份变)⇒ applySnapshot(core 重验+落盘+原子换 candidate;validate 已过 core verify,
+ *  此处失败=磁盘/状态写问题,warn 不挡 declaration 轴);absent-after-present / prompts 键整体消失
+ *  ⇒ applyDisabled(闸关=显式撤下语义的 catalog 轴半场,离线重启不复活)。幂等安全:同 envelope
+ *  重放=同 digest 覆盖写。 */
 export declare function applyCatalogToSource(source: {
     applySnapshot(raw: unknown): Promise<{
         ok: true;
@@ -20,11 +53,24 @@ export declare function applyCatalogToSource(source: {
         reason: string;
     }>;
     applyDisabled(sourceRevision: string): Promise<void>;
+    /** codex-2 F2(restart-owed disable):撤下写盘失败后重启,内存 prev 丢了但持久态还 active——
+     *  以 source 自身的 live candidate 为准判「欠 disable」,不是只看内存 prev。 */
     current?(): unknown;
 }, next: PromptsDomainFaces | undefined, prev: PromptsDomainFaces | undefined, log: {
     info: (msg: string, meta?: Record<string, unknown>) => void;
     warn: (msg: string, meta?: Record<string, unknown>) => void;
 }, phase: string): Promise<boolean>;
+/**
+ * 选包+投影:该 scenario 的终形声明数组(`scenarioOverrides[s] ?? sections`)→ typed `stableBlocks`
+ * 钩子(声明**逐字**透传,含 contentHash——core 1.315 校验后进 manifest)。空数组在 validate 已拒
+ * (F4:空替换集非 v1 语义),所以这里恒有非空声明——恒返回 provider(center-wins 无死分支)。
+ */
 export declare function centerPromptProvider(prompts: EffectiveCenterPrompts, scenarioName: string): PromptProvider;
+/** codex R3(appendSystemPrompt 案):该 scenario 的终形 center 声明里是否有「已组装 identity」——core 的
+ *  M9 迁移卫在 provider.stableBlocks 的 identity 声明上探同三锚,命中即走 pass-through 臂(其保留集无
+ *  `core/role.append`,任何 append rider/outputStyle 会被静默丢)。选包与 {@link centerPromptProvider}
+ *  同式(`overrides[s] ?? sections`);锚谓词由调用方注入(task-settings `hasConstitutionAnchors` 单真源)。
+ *  [1057]①f 的「server 不做语义复检」不动:这不是复检语义,是为 capabilities.appendSystemPrompt 的诚实面
+ *  探 core 会走哪条臂。 */
 export declare function centerIdentityAssembled(prompts: EffectiveCenterPrompts, scenarioName: string, isAssembled: (text: unknown) => boolean): boolean;
 //# sourceMappingURL=center-prompts.d.ts.map

package/dist/capabilities/center-prompts.js

@@ -1,14 +1,46 @@
+/**
+ * center prompts 消费投影腿([1043]④/[1050]③ 分工:web 承存储+covering 解析+下发,server 承本模块;
+ * [1057] 下发形定稿 / [1061] registry-core 0.10.16 schema / [1062]⑤「server 零新义务=逐字透传」)。
+ *
+ * 链路:center(sema-web)把 covering 走完的**基线终形**经 `GET /api/config/effective` 的 additive
+ * `prompts` key 下发 → 本模块按任务 scenario 选包(`scenarioOverrides[s] ?? sections`,整包替换非增量,
+ * [1057]①c)→ 声明数组**逐字**(含 opt-in `contentHash`,core 1.315 校验+manifest 透传)喂 core 既有
+ * typed `stableBlocks` 钩子。守卫全在 core(id 规范/slot 闭集/core/ 命名空间拒绝/identity 三锚
+ * pass-through/锁定槽不可写)——server 不做语义复检([1057]①f:identity 完整角色层由 center 编辑面把关)。
+ *
+ * 仅有的一层「形校验」不是语义复检,是**防炸底线**(详见其现居所 `src/prompts-domain-validate.ts`——
+ * 判形半场已下沉到该中立叶子,本文件 re-export 保兼容;design/158 S6,lens2 §G):core 对坏形声明的
+ * 守卫是 THROW(assemble 期),server 在采用前做结构判形,坏形=拒绝采用该候选的 prompts 面。
+ *
+ * 生效语义(两段史):1.222 时 core 1.315 的 epoch 是 bundled-only(声明不进 descriptor),热换=resume
+ * 三失真,故临时 restart-to-apply;core 1.316([1068] 裁 a/[1070]d)把声明以 (id,slot,chars,contentHash?)
+ * 纳入 artifactDigest——声明变=digest 变=**下任务边界自动重 pin**(既有 legacy_migration 机制接手),
+ * 进行中会话 epoch pin 保稳。自此恢复**热采用**(main.ts boot+refresh 双点 adopt),与 center
+ * 「发布=新任务生效」产品语义对齐([1051]②b)。字节级检测只认 opt-in contentHash(文本不进 digest,
+ * 防会话可导出面字典预映)——center 链路恒逐 section 铸([1065]),本投影逐字透传即全强度。
+ */
 import { verifyPromptArtifact } from "@sema-agent/core";
 import { CORE_ENGINE_VERSION } from "../prompts-domain-validate.js";
+/** 判形半场(validateCenterPrompts/validatePromptsDomain/CORE_ENGINE_VERSION 及两 interface)已下沉到
+ *  中立叶子 `src/prompts-domain-validate.ts`(design/158 S6,lens2 §G:消 config-lkg → capabilities 的
+ *  唯一分层反向边)。此处 re-export 保兼容——既有消费者(main/run-local/测试)零改动。 */
 export { validateCenterPrompts, validatePromptsDomain, CORE_ENGINE_VERSION } from "../prompts-domain-validate.js";
+/** [985]b / [1285] — §9.4 by-digest 补拉组合店:local miss ⇒ fetchRaw(digest) 从 center 拉 envelope ⇒
+ *  core verifyPromptArtifact 全管线 + **回验「拿到的=要的」digest 逐位**(center 答非所问=丢弃)⇒
+ *  best-effort 回写 inner(下次直命中)。任何失败=undefined(诚实缺席,fail-loud 归 core 的
+ *  prompt_snapshot_unavailable——绝不拼杂交)。 */
 export function withPromptArtifactBackfill(inner, fetchRaw, log) {
+    // codex F1(补拉批):per-canonical-digest 单飞——冷副本上 N 个 pinned resume 同时 miss 同一 artifact
+    // 只发一次远拉(finally 清账);裸/大写形入口即正则化(FilePromptArtifactStore 只认 canonical 键,
+    // 不正则化=非 canonical 请求缓存永 miss 重拉)。坏形 digest 直拒(不上网)。负缓存有意不设:每次
+    // miss 都是用户驱动的 resume 尝试,量有界;404 重复由单飞在并发窗内已并。
     const inFlight = new Map();
     return {
         put: (e) => inner.put(e),
         get: async (digest, opts) => {
             const hex = digest.replace(/^sha256:/i, "").toLowerCase();
             if (!/^[0-9a-f]{64}$/.test(hex))
-                return undefined;
+                return undefined; // malformed request — never a network trip
             const canonical = `sha256:${hex}`;
             const local = await inner.get(canonical, opts);
             if (local)
@@ -24,7 +56,7 @@ export function withPromptArtifactBackfill(inner, fetchRaw, log) {
                         log.warn("center_prompts_backfill_rejected", { digest: canonical, ...(v.ok ? { got: v.artifact.artifactDigest, code: "digest_mismatch" } : { code: v.code, reason: v.reason }) });
                         return undefined;
                     }
-                    await inner.put(raw).catch(() => undefined);
+                    await inner.put(raw).catch(() => undefined); // cache best-effort
                     log.info("center_prompts_backfilled", { digest: canonical });
                     return raw;
                 }
@@ -41,11 +73,18 @@ export function withPromptArtifactBackfill(inner, fetchRaw, log) {
         },
     };
 }
+/** e/b 接线([1236]① seam/[985]e):catalog 轴的两态过渡推进 core 的 CenterPromptSource——
+ *  present(且身份变)⇒ applySnapshot(core 重验+落盘+原子换 candidate;validate 已过 core verify,
+ *  此处失败=磁盘/状态写问题,warn 不挡 declaration 轴);absent-after-present / prompts 键整体消失
+ *  ⇒ applyDisabled(闸关=显式撤下语义的 catalog 轴半场,离线重启不复活)。幂等安全:同 envelope
+ *  重放=同 digest 覆盖写。 */
 export async function applyCatalogToSource(source, next, prev, log, phase) {
+    // codex-2 F2:返回「过渡是否成功」——false 时 caller **不推进** centerPrompts(身份留在 prev),
+    // 下一拍 refresh 身份仍不等=同一过渡自动重试;吞错推进曾让失败的 apply/withdraw 永久静默。
     try {
         if (next?.catalog) {
             if (prev?.identity === next.identity)
-                return true;
+                return true; // unchanged face — no state churn
             const r = await source.applySnapshot(next.catalog);
             if (r.ok) {
                 log.info("center_prompts_catalog_applied", { phase, artifactDigest: r.artifactDigest });
@@ -55,6 +94,8 @@ export async function applyCatalogToSource(source, next, prev, log, phase) {
             return false;
         }
         if (prev?.catalog || source.current?.() !== undefined) {
+            // the axis was live (in-memory marker OR a persisted candidate surviving a restart whose disable was
+            // owed) and the face now has no catalog: fail-closed mirror of the cleared semantics — disable durably.
             await source.applyDisabled(`${phase}:catalog-absent`);
             log.info("center_prompts_catalog_disabled", { phase, note: "catalog axis withdrawn — core candidate cleared (does not revive offline)" });
         }
@@ -65,10 +106,23 @@ export async function applyCatalogToSource(source, next, prev, log, phase) {
         return false;
     }
 }
+/**
+ * 选包+投影:该 scenario 的终形声明数组(`scenarioOverrides[s] ?? sections`)→ typed `stableBlocks`
+ * 钩子(声明**逐字**透传,含 contentHash——core 1.315 校验后进 manifest)。空数组在 validate 已拒
+ * (F4:空替换集非 v1 语义),所以这里恒有非空声明——恒返回 provider(center-wins 无死分支)。
+ */
 export function centerPromptProvider(prompts, scenarioName) {
     const decls = prompts.scenarioOverrides?.[scenarioName] ?? prompts.sections;
+    // 声明数组在候选采用时已判形+冻结(main.ts ref 整体替换,数组不原位变异)——闭包直接引用,core 侧
+    // 1.315 还有声明边界快照(getter 无法让「验过的」≠「发出的」)。
     return { stableBlocks: () => decls };
 }
+/** codex R3(appendSystemPrompt 案):该 scenario 的终形 center 声明里是否有「已组装 identity」——core 的
+ *  M9 迁移卫在 provider.stableBlocks 的 identity 声明上探同三锚,命中即走 pass-through 臂(其保留集无
+ *  `core/role.append`,任何 append rider/outputStyle 会被静默丢)。选包与 {@link centerPromptProvider}
+ *  同式(`overrides[s] ?? sections`);锚谓词由调用方注入(task-settings `hasConstitutionAnchors` 单真源)。
+ *  [1057]①f 的「server 不做语义复检」不动:这不是复检语义,是为 capabilities.appendSystemPrompt 的诚实面
+ *  探 core 会走哪条臂。 */
 export function centerIdentityAssembled(prompts, scenarioName, isAssembled) {
     const decls = prompts.scenarioOverrides?.[scenarioName] ?? prompts.sections;
     return decls.some((d) => d.slot === "identity" && isAssembled(d.text));

package/dist/capabilities/code-review-council.d.ts

@@ -2,20 +2,48 @@ import { runTeamDiscussion, type Runner, type ToolSpec } from "@sema-agent/core"
 import type { Metrics } from "../observability/metrics.js";
 import type { Logger } from "../observability/logger.js";
 type TeamFn = typeof runTeamDiscussion;
+/**
+ * Code-review council (Option C+, layers L1 + L3) packaged as ONE tool, so the run model is unchanged
+ * and the orchestration is **code-driven** (deterministic — we don't rely on the model to follow a
+ * multi-step orchestration prompt, which live runs showed it doesn't do reliably).
+ *
+ * - L1 (gather): one isolated, read-only-repo-tooled subagent PER differential lens, run in PARALLEL.
+ * - L3 (arbitrate): a neutral arbiter grounds/dedups/buckets/ranks. It does not add findings.
+ * - L2 (peer debate over findings + dispute verification with member tools) is the next layer.
+ *
+ * Research basis (core's design): tooled differential exploration is the main source of real bugs;
+ * grounding + bucketing kill "imagined requirements" and stop a design preference being filed as a bug.
+ */
 interface Lens {
     name: string;
     brief: string;
 }
+/**
+ * Caller-tunable lens COUNT (OA request) — a structured cost/coverage dial, sibling of `@model` / `council` /
+ * `debate`. The deployment owns WHICH lenses (the `LENSES` order = the priority: security/correctness first =
+ * the bug-finders); the caller only picks HOW MANY. Clamp to [1, LENSES.length]; absent / non-numeric = ALL
+ * (the current default → zero regression). A named subset is deliberately NOT supported (it would force a
+ * published, maintained lens vocabulary contract; the count is the verifiable knob a "light/standard" UI needs).
+ */
 export declare function pickLenses(count?: number): readonly Lens[];
+/** Caller-settable debate rounds: a FINITE integer clamped to [1,3]; non-number / NaN / ±Infinity = undefined
+ *  (→ the council's default of 1). Mirrors `pickLenses`'s `Number.isFinite` guard — the previous inline clamp let
+ *  `NaN` through (`typeof NaN === "number"`, `Math.min(3, NaN) === NaN`), corrupting the cost metric (council). */
 export declare function clampRounds(rounds: unknown): number | undefined;
 export interface CouncilToolOptions {
+    /** Aggregate the council's (otherwise invisible) sub-task cost into metrics. */
     metrics?: Metrics;
     logger?: Logger;
+    /** L1+L2+L3: add a peer-team debate (tool-grounded) before arbitration. Default L1+L3 only. */
     debate?: boolean;
+    /** Debate rounds (when `debate`). Default 1. */
     rounds?: number;
+    /** Caller-chosen lens COUNT (cost/coverage dial). Clamped to [1, LENSES.length]; absent = all lenses. */
     lensCount?: number;
+    /** Injectable for tests; defaults to core's runTeamDiscussion. */
     teamFn?: TeamFn;
 }
+/** Build the `run_council` tool. The lead calls it once; it returns the final arbitrated review. */
 export declare function createCouncilTool(subRunner: Runner, repoTools: ToolSpec[], objective: string, opts?: CouncilToolOptions): ToolSpec;
 export {};
 //# sourceMappingURL=code-review-council.d.ts.map

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

@@ -1,30 +1,45 @@
 import { Type } from "typebox";
 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;
+import { REVIEW_LENSES, GROUNDING, LENS_SYSTEM_TPL, DEBATE_MEMBER_TPL, DEBATE_TOPIC_TPL, ARBITER_SYSTEM, ARBITER_FALLBACK_HEADER } from "./prompts/code-review.js"; // bundle-data layer
+const LENSES = REVIEW_LENSES; // roster copy lives in prompts/code-review.ts
+/**
+ * Caller-tunable lens COUNT (OA request) — a structured cost/coverage dial, sibling of `@model` / `council` /
+ * `debate`. The deployment owns WHICH lenses (the `LENSES` order = the priority: security/correctness first =
+ * the bug-finders); the caller only picks HOW MANY. Clamp to [1, LENSES.length]; absent / non-numeric = ALL
+ * (the current default → zero regression). A named subset is deliberately NOT supported (it would force a
+ * published, maintained lens vocabulary contract; the count is the verifiable knob a "light/standard" UI needs).
+ */
 export function pickLenses(count) {
     if (count == null || !Number.isFinite(count))
         return LENSES;
     const n = Math.min(LENSES.length, Math.max(1, Math.floor(count)));
     return LENSES.slice(0, n);
 }
+/** Caller-settable debate rounds: a FINITE integer clamped to [1,3]; non-number / NaN / ±Infinity = undefined
+ *  (→ the council's default of 1). Mirrors `pickLenses`'s `Number.isFinite` guard — the previous inline clamp let
+ *  `NaN` through (`typeof NaN === "number"`, `Math.min(3, NaN) === NaN`), corrupting the cost metric (council). */
 export function clampRounds(rounds) {
     if (typeof rounds !== "number" || !Number.isFinite(rounds))
         return undefined;
     return Math.min(3, Math.max(1, Math.floor(rounds)));
 }
+// Guardrail COPY (GROUNDING/templates/arbiter) lives in prompts/code-review.ts — this file keeps
+// only the fill logic. `fillPrompt` is a plain `{key}` substitution (no escaping: values are our own lens
+// names/briefs and the objective/findings the model already sees verbatim elsewhere).
 function fillPrompt(tpl, vars) {
     return tpl.replace(/\{(\w+)\}/g, (m, k) => (k in vars ? vars[k] : m));
 }
 function lensSystem(lens) {
     return fillPrompt(LENS_SYSTEM_TPL, { name: lens.name, brief: lens.brief, grounding: GROUNDING });
 }
+// L2 — peer debate persona (guardrails 5,6): cross-examine, adjust confidence, verify disputes with tools.
 function debateMemberSystem(lens) {
     return fillPrompt(DEBATE_MEMBER_TPL, { name: lens.name, brief: lens.brief });
 }
 function debateTopic(objective, findings) {
     return fillPrompt(DEBATE_TOPIC_TPL, { objective, grounding: GROUNDING, findings });
 }
+/** Build the `run_council` tool. The lead calls it once; it returns the final arbitrated review. */
 export function createCouncilTool(subRunner, repoTools, objective, opts = {}) {
     return {
         name: "run_council",
@@ -33,17 +48,23 @@ export function createCouncilTool(subRunner, repoTools, objective, opts = {}) {
         effect: "read",
         parameters: Type.Object({}),
         execute: async (_args, ctx) => {
+            // Caller-chosen lens subset (OA cost/coverage dial); default = all lenses.
             const active = pickLenses(opts.lensCount);
-            const lenses = await runLensReviews(subRunner, repoTools, objective, ctx.signal, active);
+            // Forward the parent task's AbortSignal (core ≥1.18) so the lenses/arbiter stop the instant the
+            // parent is cancelled, instead of each burning to its own timeoutSec (design/16 feature request).
+            const lenses = await runLensReviews(subRunner, repoTools, objective, ctx.signal, active); // L1
             const findings = lenses.map((l) => `### ${l.lens} reviewer\n${l.text}`).join("\n\n");
-            const converge = await runConvergence(subRunner, repoTools, objective, findings, opts, ctx.signal, active);
+            const converge = await runConvergence(subRunner, repoTools, objective, findings, opts, ctx.signal, active); // L2?+L3
+            // Cost is otherwise invisible — the sub-tasks run on a separate runner, so the parent run's
+            // stats only count the lead. Surface the real (~Nx) cost three ways:
             const totalTokens = lenses.reduce((s, l) => s + l.tokens, 0) + converge.tokens;
             const totalTurns = lenses.reduce((s, l) => s + l.turns, 0) + converge.turns;
             const tasks = active.length + (opts.debate ? active.length * (opts.rounds ?? 1) + 1 : 1);
+            // ① into the PARENT run's TaskResult.stats.nested (core 1.11 reportUsage):
             ctx.reportUsage?.({ tokens: totalTokens, turns: totalTurns, tasks });
             const mode = opts.debate ? "L1+L2+L3" : "L1+L3";
             opts.metrics?.inc("council_runs_total", { mode });
-            opts.metrics?.inc("task_tokens_total", {}, totalTokens);
+            opts.metrics?.inc("task_tokens_total", {}, totalTokens); // global counter, no labels — keep it honest
             opts.metrics?.observe("council_tokens", totalTokens);
             opts.logger?.info("council_done", { mode, lenses: lenses.length, totalTokens, totalTurns });
             return {
@@ -53,10 +74,15 @@ export function createCouncilTool(subRunner, repoTools, objective, opts = {}) {
         },
     };
 }
+/** L1 — one isolated, repo-tooled subagent per lens, run in parallel. A single lens that throws
+ *  (gateway 5xx / timeout) must NOT collapse the whole council, so failures degrade to a noted
+ *  empty lens and arbitration proceeds on the survivors. */
 async function runLensReviews(subRunner, repoTools, objective, signal, lenses) {
     const settled = await Promise.allSettled(lenses.map(async (lens) => {
         const r = await subRunner.runTask({
             objective: `${objective}\n\nReview ONLY through the ${lens.name} lens.`,
+            // Cost tiering (1.24): lenses run on the `subagent` role — cheap when MODEL_CHEAP_ID is set,
+            // else the main model. Scanning for leads doesn't need the strong model; the arbiter does.
             modelRole: "subagent",
             tools: repoTools,
             systemPrompt: lensSystem(lens),
@@ -75,6 +101,7 @@ async function runLensReviews(subRunner, repoTools, objective, signal, lenses) {
             turns: 0,
         });
 }
+/** L2 (peer debate, tool-grounded) + L3 synthesis, or — when `debate` is off — L3 arbiter alone. */
 async function runConvergence(subRunner, repoTools, objective, findings, opts, signal, lenses) {
     if (opts.debate) {
         const team = await (opts.teamFn ?? runTeamDiscussion)({
@@ -83,12 +110,14 @@ async function runConvergence(subRunner, repoTools, objective, findings, opts, s
             members: lenses.map((l) => ({ role: l.name, systemPrompt: debateMemberSystem(l) })),
             topic: debateTopic(objective, findings),
             rounds: opts.rounds ?? 1,
-            tools: repoTools,
+            tools: repoTools, // members may verify a disputed claim against the real code (Tool-MAD)
             maxTranscriptTokens: 8000,
             synthesizer: { role: "arbiter", systemPrompt: ARBITER_SYSTEM },
             limits: { timeoutSec: 400 },
-            signal,
+            signal, // 1.28: a parent abort now cascades into the debate members
         });
+        // 1.32: synthesizer 两次都失败时 `conclusion` 是 `[unavailable…]` 垃圾串，与真结论无法区分。别当结论
+        // 返回——退回未经仲裁的各 lens 原始发现（findings 在手），用户至少看到真实发现，而不是把垃圾当评审。
         if (!team.conclusionValid) {
             opts.logger?.warn("council_arbiter_failed", { failures: team.failures });
             return {
@@ -99,14 +128,18 @@ async function runConvergence(subRunner, repoTools, objective, findings, opts, s
         }
         return { review: team.conclusion, tokens: team.stats.tokens, turns: team.stats.turns };
     }
+    // L3 only — a single neutral arbiter (ground / dedup / bucket / rank). No new findings.
     const arb = await subRunner.runTask({
         objective: `Arbitrate these specialist findings into ONE final review:\n\n${findings}`,
+        // The arbiter grounds/dedups/ranks — keep it on the strong `synthesize` role (= main model).
         modelRole: "synthesize",
         systemPrompt: ARBITER_SYSTEM,
         limits: { timeoutSec: 240 },
         enableBlockedReport: false,
         signal,
     });
+    // Mirror the debate path's fallback: an empty/failed arbiter result must not surface as an empty review —
+    // hand back the raw lens findings so the caller still sees real findings, not nothing.
     const review = arb.result?.trim() || `${ARBITER_FALLBACK_HEADER}${findings}`;
     return { review, tokens: arb.stats.tokens, turns: arb.stats.turns };
 }

package/dist/capabilities/collab-wire.d.ts

@@ -1,3 +1,5 @@
+/** center /effective `collab.templates[]` 条目的服务侧结构子集(registry-core 0.7 CollabTemplate 出参兼容;
+ *  wire 类型独立成模块——投影实现随切片演进[①=TeamTemplate,1.5=named workflow defaultArgs],wire 形状不动)。 */
 export interface CollabTemplateWire {
     id: string;
     name: string;

package/dist/capabilities/collab-workflows.d.ts

@@ -1,9 +1,11 @@
 import type { CollabTemplateWire } from "./collab-wire.js";
+/** core WorkflowScriptStore.list() 行(name+description+whenToUse)——LLM 工具卡/roster 投影面。 */
 export interface CollabWorkflowListing {
     name: string;
     description?: string;
     whenToUse?: string;
 }
+/** 一条已注册的 collab 命名 workflow:执行体恒为 core 内置 team-discussion 脚本,个性全在 defaultArgs。 */
 export interface CollabWorkflowEntry {
     defaultArgs: {
         members: Array<{
@@ -32,9 +34,14 @@ export interface CollabWorkflowProjection {
 }
 export declare function projectCollabToWorkflows(templates: readonly CollabTemplateWire[] | undefined): CollabWorkflowProjection;
 export declare function registerCollabWorkflows(workflows: Record<string, CollabWorkflowEntry>): void;
+/** composite WorkflowScriptStore 的 resolveName 前段:collab 命中 ⇒ 内置 team-discussion 脚本+本模板
+ *  defaultArgs(同名 SHADOW core 内置,design/140 §6 1c)。🔴 Object.hasOwn — `name` 是模型供给的
+ *  (run-workflow-tool 原样传 rawName):裸索引会让 Object.prototype 成员名("constructor"/"toString"/
+ *  "__proto__"…)假命中 ⇒ 零模板注册也能烧真讨论、且同名文件 store 条目被遮蔽(对抗评审 2026-07-11 MED)。 */
 export declare function resolveCollabWorkflow(name: string): {
     script: string;
     defaultArgs: unknown;
 } | undefined;
+/** composite store 的 list() 段(同步——workflow 工具卡只吃同步 list,core 契约注释)。 */
 export declare function listCollabWorkflows(): CollabWorkflowListing[];
 //# sourceMappingURL=collab-workflows.d.ts.map