@sema-agent/server 1.322.0 → 2.0.0

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

package/dist/capabilities/collab-workflows.js

@@ -1,9 +1,34 @@
+/**
+ * collab → named-workflow projection — 翻译层**切片 1.5**(design/140 统一解:
+ * 「模式=内置命名 workflow profile,一期零新引擎机制」;core 1.263.0 三件落地后的靶点切换)。
+ *
+ * 切片① 的 runTeamDiscussion 投影(collab-project.ts)已随本切片**整体替换**(同款纪律:别留双路径
+ * 降级)。新形态:每个可投影的 CollabTemplate 翻译成一条**命名 workflow 注册条目**——
+ *
+ *   `Workflow({name: <collab id>})` ⇒ 执行体 = core 内置 `TEAM_DISCUSSION_SCRIPT`(pure script content,
+ *   零新机制)+ `defaultArgs` = 本模板的 slots/rounds/finalizer 翻译(args 合并链第二级:调用时 args >
+ *   本注册 defaults > 脚本内置兜底,core `mergeWorkflowArgs` 在 tool-resolve 时点快照)。center「只配模式
+ *   各 slot 的模型」的拍板意图恰好=defaultArgs 这一级;调用者仍可用 args.topic/members 覆盖。
+ *
+ * 可投影子集(团队讨论 profile 能忠实执行的语义;其余整条跳过+结构化上报,绝不静默降级):
+ *   topology ∈ {ring, pair}(round-based 顺序发言=脚本真实形态;star/layered 等 core 后续 profile)∧
+ *   finalizer.type = "summarize"(→脚本 finalizer;judge/vote/fuse/verify 裁决族=后续 profile)∧
+ *   sharedContext = {transcript, session} ∧ 全 slot 无 tools(工具绑定=执行面后续)。
+ *
+ * 语义注记(投影成功但记录):脚本对 members cap 6 / rounds cap 5(确定性截断)——超界模板照投+note;
+ * CollabTemplate.budget=模板级预算无 per-name workflow 通道(WorkflowLimits 是部署级、per-child 强制轴
+ * 已有)→ 记 note,引擎 budget 硬顶+部署 maxTask* 闸兜底(与切片① 结论一致)。
+ *
+ * 纯函数投影 + 模块级可变注册表(registerTeams 同款单例姿势,applyEffective boot+refresh 热更);
+ * 消费点 = main.ts 的 composite WorkflowScriptStore(resolveName 先查这里——**同名 SHADOW core 内置**,
+ * design/140 §6 1c 契约)。
+ */
 import { TEAM_DISCUSSION_SCRIPT } from "@sema-agent/core";
 export function projectCollabToWorkflows(templates) {
     const out = { workflows: {}, skipped: [], notes: [] };
     for (const t of templates ?? []) {
         if (t.enabled === false)
-            continue;
+            continue; // 运营态关闭(不进 skipped)
         if (t.topology !== "ring" && t.topology !== "pair") {
             out.skipped.push({ id: t.id, reason: `topology "${t.topology}" awaits a dedicated profile (design/140 follow-on)` });
             continue;
@@ -22,11 +47,17 @@ export function projectCollabToWorkflows(templates) {
             out.skipped.push({ id: t.id, reason: "slot tools binding awaits the execution slice" });
             continue;
         }
+        // finalizer.slot → 脚本 finalizer(该席位退出讨论席)。slot **未配** ⇒ 脚本内置综合官兜底(合法形态);
+        // slot 配了但**悬空**(指向不存在的席位——拼错/编辑漂移)⇒ 整条跳过(静默回退默认综合官
+        // = 模板意图被悄悄改写,违「绝不静默降级」纪律;center zod 不做跨字段存在性校验,这里是唯一防线)。
         const finSlot = t.finalizer.slot !== undefined ? t.slots.find((s) => s.id === t.finalizer.slot) : undefined;
         if (t.finalizer.slot !== undefined && finSlot === undefined) {
             out.skipped.push({ id: t.id, reason: `finalizer.slot "${t.finalizer.slot}" does not match any slot id (dangling reference)` });
             continue;
         }
+        // 对抗评审 2026-07-11(MED):finalizer slot 合法可为 cardinality-N 多成员(registry-core 只约束
+        // cardinality=1 ≤1 人),但 team-discussion 的 finalizer 是单席——members[1..] 无席可坐。不静默丢人:
+        // 首成员任综合官,其余 note 上报(与 cap 截断同款有损注记纪律)。
         if ((finSlot?.members?.length ?? 0) > 1) {
             out.notes.push({ id: t.id, note: `finalizer slot "${finSlot.id}" carries ${finSlot.members.length} members — only the first seats as the synthesizer (single-seat finalizer profile)` });
         }
@@ -35,6 +66,10 @@ export function projectCollabToWorkflows(templates) {
         const finalizer = finPrompt !== undefined || finModel !== undefined
             ? { ...(finPrompt !== undefined ? { prompt: finPrompt } : {}), ...(finModel !== undefined ? { model: finModel } : {}) }
             : undefined;
+        // 讨论席展开(cardinality "N" 逐成员出席,role 序号唯一;member 镜头 > slot 镜头;T1 modelRef 缺省=
+        // 不设 model ⇒ 脚本/引擎跟随调用者当前模型,零特判)。members 为空的席位=slot 镜头即人设,一人出席。
+        // cardinality 声明与 members 实况分叉(=1 却配了多成员)不静默 flatten——全员照展开
+        // (丢成员=更糟的静默降级)但 note 上报,center 编辑面可据此标注修正。
         const members = [];
         for (const s of t.slots) {
             if (s === finSlot)
@@ -59,6 +94,8 @@ export function projectCollabToWorkflows(templates) {
             defaultArgs: { members, rounds: t.rounds.max, ...(finalizer ? { finalizer } : {}) },
             listing: {
                 name: t.id,
+                // description=center 起的显示名+描述(工具卡人话);whenToUse 留给 center 未来字段——缺席时
+                // 工具卡回落 description(core workflowWhenToUseText 链)。
                 description: [t.name, t.description].filter(Boolean).join(" — ") || t.id,
             },
         };
@@ -75,15 +112,21 @@ export function projectCollabToWorkflows(templates) {
     }
     return out;
 }
+// ── 模块级注册表(registerTeams 同款可变单例;applyEffective boot+refresh 热更,非粘:整表替换)────────
 let REGISTRY = {};
 export function registerCollabWorkflows(workflows) {
     REGISTRY = { ...workflows };
 }
+/** 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 function resolveCollabWorkflow(name) {
     if (!Object.hasOwn(REGISTRY, name))
         return undefined;
     return { script: TEAM_DISCUSSION_SCRIPT, defaultArgs: REGISTRY[name].defaultArgs };
 }
+/** composite store 的 list() 段(同步——workflow 工具卡只吃同步 list,core 契约注释)。 */
 export function listCollabWorkflows() {
     return Object.values(REGISTRY).map((e) => e.listing);
 }

package/dist/capabilities/oa-tools.d.ts

@@ -1,4 +1,10 @@
 import type { ToolSpec } from "@sema-agent/core";
+/**
+ * OA scenario — tools are thin HTTP clients to the OA backend's existing APIs (read = /api/v1/*,
+ * write = /api/assets/*). The shared service token + the request's principal are forwarded so OA
+ * enforces THAT end-user's RBAC + audit (the service never holds per-user creds). Decoupled: the
+ * service knows no OA schema/DB — OA stays the source of truth (its /api/v1/meta is self-describing).
+ */
 export interface OaCtx {
     baseUrl: string;
     token: string;

package/dist/capabilities/oa-tools.js

@@ -39,6 +39,16 @@ export function oaTools(ctx) {
                 return e; const x = a; return oaFetch(ctx, `/api/assets/${encodeURIComponent(x.type)}/${encodeURIComponent(x.id)}/transition`, { method: "POST", body: { to: x.to, note: x.note ?? null } }); } },
     ];
 }
+// OA business prompt MOVED OUT — migration complete (design/29, 2026-06-05). Persona / 工作准则 / UI
+// markers (::FORM:: / ::GOTO:: / ::SUGGEST:: / ::ISSUE_FORM::) / 分级确认 / 报bug流程 are OA's business,
+// and OA now injects the WHOLE thing per request via `request.systemPrompt` (it holds the service token,
+// content is stable per OA version → cacheable prefix; page context still rides `objective`). Keeping
+// any of it here would just DUPLICATE OA's prompt, so the base is EMPTY — single source of truth = OA.
+// The service stays business-agnostic: it provides the oa_* tools (referenced by NAME from OA's prompt;
+// they carry their own descriptions) and nothing else. `stablePrompt` keeps STABLE→VARIABLE order —
+// OA's systemPrompt is appended after this (empty) base, before core's <user_memory>.
+// (::ISSUE_FORM:: is parsed/rendered + submitted entirely by OA's frontend via OA /api/ai/issue — the
+//  service never touches it; `open_gitea_issue` remains only as the unattended/automated fallback.)
 const OA_SYSTEM = "";
 export const oaPrompt = stablePrompt(OA_SYSTEM);
 //# sourceMappingURL=oa-tools.js.map

package/dist/capabilities/prompt.d.ts

@@ -1,3 +1,17 @@
 import type { PromptProvider } from "@sema-agent/core";
+/**
+ * Build a scenario's prompt provider from just its ROLE base, on core 1.243's 提示词主权 contract:
+ * `stableSystem` returns ONLY the role layer (base + the task's own systemPrompt) and **core appends
+ * the constitution structurally** — harness/safety blocks (Truth/CYBER_RISK/URL_SAFETY), mode blocks,
+ * AND the memory safety/hygiene guidance (`constitutionBlocks`), plus the volatile `<user_memory>`
+ * tail LAST (design/12 prefix-cache discipline; guarded in CI by `assertPromptCacheFriendly`).
+ *
+ * History: the pre-1.243 seam made this helper's whole-prompt replacement silently DROP
+ * core's constitution — oa/code-review/team ran with zero safety blocks. Same batch also moved
+ * MEMORY_SAFETY/MEMORY_HYGIENE into the constitution layer, so the hand-composition this helper used
+ * to do (core 1.62, design/41) would now DOUBLE-inject them — both removed; core owns the discipline
+ * (consolidation mutual-exclusion included). This stays a thin role-layer join so scenarios don't
+ * re-implement the same two-line body five times.
+ */
 export declare function stablePrompt(base: string): PromptProvider;
 //# sourceMappingURL=prompt.d.ts.map

package/dist/capabilities/prompt.js

@@ -1,3 +1,17 @@
+/**
+ * Build a scenario's prompt provider from just its ROLE base, on core 1.243's 提示词主权 contract:
+ * `stableSystem` returns ONLY the role layer (base + the task's own systemPrompt) and **core appends
+ * the constitution structurally** — harness/safety blocks (Truth/CYBER_RISK/URL_SAFETY), mode blocks,
+ * AND the memory safety/hygiene guidance (`constitutionBlocks`), plus the volatile `<user_memory>`
+ * tail LAST (design/12 prefix-cache discipline; guarded in CI by `assertPromptCacheFriendly`).
+ *
+ * History: the pre-1.243 seam made this helper's whole-prompt replacement silently DROP
+ * core's constitution — oa/code-review/team ran with zero safety blocks. Same batch also moved
+ * MEMORY_SAFETY/MEMORY_HYGIENE into the constitution layer, so the hand-composition this helper used
+ * to do (core 1.62, design/41) would now DOUBLE-inject them — both removed; core owns the discipline
+ * (consolidation mutual-exclusion included). This stays a thin role-layer join so scenarios don't
+ * re-implement the same two-line body five times.
+ */
 export function stablePrompt(base) {
     return {
         stableSystem: ({ userSystemPrompt }) => [base, userSystemPrompt].filter(Boolean).join("\n\n"),

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

@@ -1,11 +1,25 @@
+/**
+ * Code-review council copy (bundle-data layer). Pure data — placeholders are `{name}`-style,
+ * filled by the consumer (code-review-council.ts fillPrompt). Guardrail rationale lives with the
+ * consumer's comments; this file is ONLY the words.
+ */
+/** The deployment-owned lens roster. Order = priority (security/correctness first = the bug-finders);
+ *  the caller dials COUNT only (pickLenses), never a named subset. */
 export declare const REVIEW_LENSES: ReadonlyArray<{
     name: string;
     brief: string;
 }>;
+/** Guardrails 2-5: evidence grounding (a CONFIDENCE signal, not a delete), requirement anchoring,
+ *  bucketing, severity×confidence. */
 export declare const GROUNDING: string;
+/** L1 lens reviewer system prompt. Placeholders: {name} {brief} {grounding}. */
 export declare const LENS_SYSTEM_TPL: string;
+/** L2 peer-debate persona (guardrails 5,6). Placeholders: {name} {brief}. */
 export declare const DEBATE_MEMBER_TPL: string;
+/** L2 debate topic body. Placeholders: {objective} {grounding} {findings}. */
 export declare const DEBATE_TOPIC_TPL: string;
+/** Guardrails 4,7: arbitration is not summary — no new findings, ground/dedup/bucket/rank only. */
 export declare const ARBITER_SYSTEM: string;
+/** No-arbiter fallback header ({findings} appended by the consumer). */
 export declare const ARBITER_FALLBACK_HEADER = "[council \u4EF2\u88C1\u65E0\u8F93\u51FA\u2014\u2014\u4EE5\u4E0B\u662F\u672A\u7ECF\u4EF2\u88C1\u7684\u5404 lens \u539F\u59CB\u53D1\u73B0]\n\n";
 //# sourceMappingURL=code-review.d.ts.map