@sema-agent/server 7.8.1 → 7.10.0

package/dist/hooks/hook-runner.js

@@ -499,35 +499,50 @@ async function runLlmHook(entry, payload, ctx, extra) {
     // 顺序是承重的 —— 包装句逐字预设会话在上文,放反了那句话本身就是在骗模型。
     const prompt = extra ? `${extra.transcript}\n\n---\n\n${wrapCondition("Stop", substituted)}` : substituted;
     // 载体外再包一层硬顶:契约说载体自己兜超时,但一个部署组装 bug 不该能挂死工具门(纵深)。
-    const hardTop = new Promise((r) => setTimeout(() => r({ ok: false, error: "hook llm hard-timeout backstop fired (carrier did not settle within timeoutMs+5s — deployment assembly bug)", code: "hard_timeout" }), timeoutMs + 5_000).unref?.());
-    const invoke = () => Promise.race([
-        call({
-            prompt,
-            ...(entry.model ? { model: entry.model } : {}),
-            timeoutMs,
-            ...(extra ? { system: extra.system, maxOutputTokens: CC_EVALUATOR_MAX_OUTPUT_TOKENS } : {}),
-        }),
-        hardTop,
-    ]).catch((e) => ({ ok: false, error: String(e) }));
-    let res = await invoke();
-    // 🔴 **"一个字都没吐出来"重试一次**(仅 CC 评估者路)。这个失败形的后果是**判词被丢弃 ⇒ fail-open**
-    // (该拦没拦),而它是**瞬态**的(推理档模型偶尔把额度用在 thinking 上)。
-    // ⚠️ 只重试**无内容**,不重试"有内容但读不懂" —— 后者重试一次多半还是读不懂,而且那一格按设计就该放行。
-    if (extra && !res.ok && res.code === "no_content") { // B8:判别走码不走文案(v3.1 批2)
-        ctx.logger.warn("hook_llm_no_content_retry", { event: "Stop" });
-        res = await invoke();
-        // 重试之后**仍然**没有内容 ⇒ 这一轮的守卫确实没能评估。发观测帧(纯 observe,不改变运行)——
-        // 方向仍是 fail-open,但用户/壳侧要能知道「这轮没看住」,否则那个放行与「已达成」无法区分。
-        if (!res.ok && res.code === "no_content") {
-            ctx.onHookNotice?.({ kind: "hook_decision_unavailable", event: "Stop", reason: "no_content", detail: "carrier returned no content (after one retry)" });
+    // A-002.12:硬顶只 unref 不清 ⇒ 每次被门到的工具调用留一只带闭包的定时器,最长挂
+    // MAX_HOOK_TIMEOUT_SECONDS+5s=605s(工具门是热路径,一个任务几十上百次)。整个函数收在
+    // try/finally 里,任何出口都 clearTimeout。
+    // 🔴 硬顶**一只到底**、两次 invoke 共用(语义原样不动):它兜的是「本次 hook 判决整体不许挂死」,
+    // 不是「每次载体调用各给一个新窗」——改成 per-invoke 会把最坏墙钟翻倍。
+    let hardTopTimer;
+    const hardTop = new Promise((r) => {
+        hardTopTimer = setTimeout(() => r({ ok: false, error: "hook llm hard-timeout backstop fired (carrier did not settle within timeoutMs+5s — deployment assembly bug)", code: "hard_timeout" }), timeoutMs + 5_000);
+        hardTopTimer.unref?.();
+    });
+    try {
+        const invoke = () => Promise.race([
+            call({
+                prompt,
+                ...(entry.model ? { model: entry.model } : {}),
+                timeoutMs,
+                ...(extra ? { system: extra.system, maxOutputTokens: CC_EVALUATOR_MAX_OUTPUT_TOKENS } : {}),
+            }),
+            hardTop,
+        ]).catch((e) => ({ ok: false, error: String(e) }));
+        let res = await invoke();
+        // 🔴 **"一个字都没吐出来"重试一次**(仅 CC 评估者路)。这个失败形的后果是**判词被丢弃 ⇒ fail-open**
+        // (该拦没拦),而它是**瞬态**的(推理档模型偶尔把额度用在 thinking 上)。
+        // ⚠️ 只重试**无内容**,不重试"有内容但读不懂" —— 后者重试一次多半还是读不懂,而且那一格按设计就该放行。
+        if (extra && !res.ok && res.code === "no_content") { // B8:判别走码不走文案(v3.1 批2)
+            ctx.logger.warn("hook_llm_no_content_retry", { event: "Stop" });
+            res = await invoke();
+            // 重试之后**仍然**没有内容 ⇒ 这一轮的守卫确实没能评估。发观测帧(纯 observe,不改变运行)——
+            // 方向仍是 fail-open,但用户/壳侧要能知道「这轮没看住」,否则那个放行与「已达成」无法区分。
+            if (!res.ok && res.code === "no_content") {
+                ctx.onHookNotice?.({ kind: "hook_decision_unavailable", event: "Stop", reason: "no_content", detail: "carrier returned no content (after one retry)" });
+            }
         }
+        if (!res.ok) {
+            return res.code === "hard_timeout"
+                ? { code: null, stdout: "", stderr: "", timedOut: true }
+                : { code: null, stdout: "", stderr: "", timedOut: false, spawnError: clip(res.error, 500) };
+        }
+        return { code: 0, stdout: clip(res.text, 1024 * 1024), stderr: "", timedOut: false };
     }
-    if (!res.ok) {
-        return res.code === "hard_timeout"
-            ? { code: null, stdout: "", stderr: "", timedOut: true }
-            : { code: null, stdout: "", stderr: "", timedOut: false, spawnError: clip(res.error, 500) };
+    finally {
+        if (hardTopTimer !== undefined)
+            clearTimeout(hardTopTimer);
     }
-    return { code: 0, stdout: clip(res.text, 1024 * 1024), stderr: "", timedOut: false };
 }
 async function runHttpHook(entry, payload, ctx) {
     const timeoutMs = Math.min(entry.timeout ?? DEFAULT_HOOK_TIMEOUT_SECONDS, MAX_HOOK_TIMEOUT_SECONDS) * 1000;

package/dist/http/routes/approvals-assistant.d.ts

@@ -32,6 +32,13 @@ export declare function handleApprovalsAssistant(req: IncomingMessage, res: Serv
  * heartbeats + retries (never kills the stream); a 15-min cap + req-close end it (parity with streamTaskTrace).
  * Poll-granularity caveat: a pending that resolves AND re-suspends on the same (session,toolCallId) within one
  * interval shows no delta — acceptable (the live snapshot is always eventually correct; no decision is missed).
+ *
+ * A-002.19(2026-08-09 亲验定性=设计接受,非欠账):每连接自跑 pollMs 轮询打共享 checkpoint 表,
+ * 之所以不建 fan-out/单轮询器基建——①消费方=portal 运营面,并发连接数量级为个位(不是用户面);
+ * ②listPending 走 (scope,status) 索引,单查成本与一次 /v1/approvals 轮询同阶,而本路正是替代客户端
+ * ~10s 轮询的(净负载持平或更低);③DB blip 已 fail-soft(心跳+下拍重试),15-min cap 兜顶。连接
+ * 数假设若被打破(portal 多开成常态),届时把 poll 收敛为进程内单轮询器多路复用——那是量级触发的
+ * 演化,不是现在的缺陷。
  */
 export declare function streamApprovals(req: IncomingMessage, res: ServerResponse, cs: Pick<CheckpointStoreFull, "listPending">, scope: string | undefined, pollMs?: number): Promise<void>;
 //# sourceMappingURL=approvals-assistant.d.ts.map

package/dist/http/routes/approvals-assistant.js

@@ -178,9 +178,9 @@ async function handleApprovalsAssistantBody(req, res, url, ctx, miss) {
                 };
             }))
             // severity DESC, then **explicitly** oldest-first within a tier ([2027] 第五节欠单②,红先绿后:
-            // test/assistant-triage-ordering.test.ts)。旧姿势只比 severity,靠「listByScope 是 created_at ASC
+            // test/assistant-triage-ordering.test.ts)。旧姿势只比 severity,靠「listByScope 是 created_at_ms ASC
             // + Array#sort 稳定」来兑现 §2 那句 oldest-first —— 而那个前提**只在本仓的 SQL 后端成立**
-            // (checkpoint-store-sql.ts 的 `ORDER BY created_at ASC`):core 的 `CheckpointStore.listByScope` 接口
+            // (checkpoint-store-sql.ts 的 `ORDER BY created_at_ms ASC`):core 的 `CheckpointStore.listByScope` 接口
             // 零顺序声明,InMemory/File 两个实现直接遍历 Map(LOCAL 车道包的正是 File store)⇒ 那句承诺过去是
             // **后端相关**的。比较器自带兜底后它与 store 顺序无关。形与 listPending 的同族 sort 逐字一致
             // (checkpoint-store-sql.ts `|| a.createdAt - b.createdAt`)。createdAt 缺席(pre-1.116 投影的老行)
@@ -667,6 +667,13 @@ const APPROVALS_STREAM_POLL_MS = 3000;
  * heartbeats + retries (never kills the stream); a 15-min cap + req-close end it (parity with streamTaskTrace).
  * Poll-granularity caveat: a pending that resolves AND re-suspends on the same (session,toolCallId) within one
  * interval shows no delta — acceptable (the live snapshot is always eventually correct; no decision is missed).
+ *
+ * A-002.19(2026-08-09 亲验定性=设计接受,非欠账):每连接自跑 pollMs 轮询打共享 checkpoint 表,
+ * 之所以不建 fan-out/单轮询器基建——①消费方=portal 运营面,并发连接数量级为个位(不是用户面);
+ * ②listPending 走 (scope,status) 索引,单查成本与一次 /v1/approvals 轮询同阶,而本路正是替代客户端
+ * ~10s 轮询的(净负载持平或更低);③DB blip 已 fail-soft(心跳+下拍重试),15-min cap 兜顶。连接
+ * 数假设若被打破(portal 多开成常态),届时把 poll 收敛为进程内单轮询器多路复用——那是量级触发的
+ * 演化,不是现在的缺陷。
  */
 export async function streamApprovals(req, res, cs, scope, pollMs = APPROVALS_STREAM_POLL_MS) {
     // JSON-encode the (sessionId, toolCallId) pair so distinct pendings can NEVER collide into one Map key,

package/dist/http/routes/side-query.d.ts

@@ -8,5 +8,9 @@
  */
 import type { IncomingMessage, ServerResponse } from "node:http";
 import type { RouteCtx } from "../route-ctx.js";
+/** 表内=core 的前置校验形(客户端可改请求)⇒ 400;表外一律 500。 */
+export declare function isCorePreflightValidationError(message: string): boolean;
+/** 供跨仓锚门读:门要拿这张表去装机的 core 里逐条对账(见上方 doc)。 */
+export declare const CORE_PREFLIGHT_VALIDATION_ANCHORS: readonly string[];
 export declare function handleSideQuery(req: IncomingMessage, res: ServerResponse, url: string, ctx: RouteCtx): Promise<boolean>;
 //# sourceMappingURL=side-query.d.ts.map

package/dist/http/routes/side-query.js

@@ -4,6 +4,79 @@ import { cacheFamilyOfMirror } from "../../budget.js";
 import { redactSecrets } from "../../trace/redact.js";
 import { sendJson, sendError, httpErrorCode, msg } from "../send.js";
 import { gatedPrincipal } from "../principal-gate.js";
+/**
+ * A-002.2 —— core 前置校验异常的分类词表(400 客户端可改 / 500 我方缺陷)。
+ *
+ * 🔴 **亲验记账(core 5.x dist,本批复核)**:core 在这条路径上抛的是**裸 `Error`**,异常对象上
+ * 没有 `code`/`name`/`status` 任何结构化判别位 ——
+ *   · `core/roles.js:8`   `throw new Error(\`Unknown model ref "\${ref}". …\`)`
+ *   · `core/roles.js:179` `throw new Error(\`No model for role "\${start}": …\`)`
+ * 所以「优先消费结构化位、正则降兜底」在当前 core 上**无位可消费**:这里如实停在文案匹配,并把跨仓
+ * 耦合交给一道机器门看着 —— test/side-query-http.test.ts 的「A-002.2 跨仓锚」**调装机 core 的两个导出
+ * 解析器把异常真抛出来**,拿真 message 过本谓词。
+ * 🔴 为什么不是「扫 core 源码里有没有这两句字面」:那种锚有一个致命假绿形(codex 复审 medium,已采纳)
+ * ——core 完全可以保留字面却在抛出时加前缀/包一层,源码锚照绿而 `startsWith` 当场失效,客户端错误静默
+ * 变成 500。真抛出预言机没有这个缝(它当场就揪出了下面 `modelRole` 那条连带缺陷)。
+ * core 哪天给这两处加了 code,本函数就该改成读那个 code、文案匹配退成兜底 —— 那道门会先红,提醒动这里。
+ *
+ * 🪦 **第三臂已删(死支确认)**:原表还有 `requires a non-empty messages array`(core
+ * `core/side-query.js:10`)。它**不可达** —— 本路由在调 core 之前就有
+ * `!Array.isArray(body.messages) || body.messages.length === 0 ⇒ 400 request.body_shape` 的前拦
+ * (见下方路由体),两个条件与 core 那条判据逐字同集,所以 core 那句永远轮不到抛。留着=养一条永假的
+ * 分支,删了并立此墓碑;前拦一旦被摘,side-query-http 的「空/非数组 messages → 400 request.body_shape」
+ * 两格先红。
+ *
+ * 失败方向:表外一律 500(响亮、可告警、可重试),绝不把不认识的异常猜成客户端错误。
+ */
+const CORE_PREFLIGHT_VALIDATION_PREFIXES = ["Unknown model ref ", "No model for role "];
+/** 表内=core 的前置校验形(客户端可改请求)⇒ 400;表外一律 500。 */
+export function isCorePreflightValidationError(message) {
+    return CORE_PREFLIGHT_VALIDATION_PREFIXES.some((prefix) => message.startsWith(prefix));
+}
+/** 供跨仓锚门读:门要拿这张表去装机的 core 里逐条对账(见上方 doc)。 */
+export const CORE_PREFLIGHT_VALIDATION_ANCHORS = CORE_PREFLIGHT_VALIDATION_PREFIXES;
+/**
+ * A-002.2 连带 —— `modelRole` 的**选路可达性**门。
+ *
+ * 🔴 由来(A-002.2 的真抛出预言机当场揪出来的,源码扫描锚与 mock 都照不到):core 的 `ModelRole` 是
+ * 闭集(8 值),而 core 的 `resolveTaskModel` 在**无显式 model** 时要走 `FALLBACK[start]` —— 表外角色
+ * 在那张表里是 `undefined`,于是真抛 `TypeError: FALLBACK[start] is not iterable`。一条**客户端可改**的
+ * 输入错误,以「服务器内部错误 + 可重试」的面目回给客户端;而且这一条连 400/500 分类都救不了(那句
+ * TypeError 文案里没有任何可分类的痕迹)。所以拒在本层。
+ *
+ * ⚠️ **只在这个字段真参与选路时才拒**(codex 复审 R2 medium,已采纳并收窄):`spec.model` 在场时
+ * `resolveTaskModel` 走**短路分支**,压根不碰 `FALLBACK` —— `{model:"<有效 ref>", modelRole:"cheap"}`
+ * 是一条**今天就能跑通**的既有形,而 SDK 的 `SideQueryRequest.modelRole` 又逐字声明为开放 `string`
+ * (spec/openapi.yaml)。对它一并拒 = 无版本协商地收窄已发布契约。首版正是这么写的,复审逮到。
+ * 同理也不能「有 model 时把表外角色丢掉」:core 会拿 `merged[start]` 取该角色上的 thinking/systemPrompt
+ * (`runSideQuery` 里 `spec.systemPrompt ?? resolved.systemPrompt`),丢掉它会让配置好的 `default` 角色的
+ * systemPrompt 意外生效 —— 那也是行为改动。⇒ 有 model 时**原样透传**,行为逐字不变。
+ *
+ * 表是 `Record<ModelRole, true>` 穷举:core 增删一个角色词,本表编译期先红(闭集词表的成文纪律)。
+ */
+const MODEL_ROLE_TABLE = {
+    default: true,
+    summarize: true,
+    subagent: true,
+    team: true,
+    synthesize: true,
+    advisor: true,
+    verifier: true,
+    classifier: true,
+};
+/** 表内 ⇒ 收窄成 `ModelRole`(类型守卫)。门用它判「这个角色能不能自己选出模型」。 */
+function isModelRole(value) {
+    return typeof value === "string" && Object.hasOwn(MODEL_ROLE_TABLE, value);
+}
+/**
+ * 线上契约(SDK `SideQueryRequest.modelRole: string`)比 core 的 `ModelRole` 闭集**宽**,而 core 对该字段的
+ * 实际用法是**开放键查表**(`mergeRoles(...)[start]`,查不到即空)——所以表外值在有显式 model 时是合法且
+ * 惰性的。这处窄化断言是那道宽窄差的**唯一**落点(其余路径已由上面的门挡住),集中在此并说明缘由,
+ * 而不是散在装配字面量里当作无声的裸 cast。
+ */
+function passthroughModelRole(value) {
+    return value;
+}
 export async function handleSideQuery(req, res, url, ctx) {
     const miss = { fell: false };
     await handleSideQueryBody(req, res, url, ctx, miss);
@@ -55,12 +128,19 @@ async function handleSideQueryBody(req, res, url, ctx, miss) {
                 sendError(res, 400, "request.field_invalid", "invalid thinking level");
                 return;
             }
+            // 选路可达性门(见 MODEL_ROLE_TABLE 顶注):**仅当该字段真参与选路**(无显式 model)时,表外角色
+            // 才 fail-closed 在这里 —— 那条路上 core 抛的是无从分类的 TypeError,400/500 分类救不回来。
+            // 有显式 model ⇒ core 走短路分支,该值惰性,原样透传(既有可用形,不许无版本协商地收窄)。
+            if (typeof body.model !== "string" && body.modelRole !== undefined && !isModelRole(body.modelRole)) {
+                sendError(res, 400, "request.field_invalid", `invalid modelRole (expected one of: ${Object.keys(MODEL_ROLE_TABLE).join(", ")}) — a role only resolves a model when 'model' is absent`);
+                return;
+            }
             if (ac.signal.aborted)
                 return; // client already gone — don't start the brain call at all
             const spec = {
                 messages: body.messages,
                 ...(typeof body.model === "string" ? { model: body.model } : {}),
-                ...(typeof body.modelRole === "string" ? { modelRole: body.modelRole } : {}),
+                ...(typeof body.modelRole === "string" ? { modelRole: passthroughModelRole(body.modelRole) } : {}),
                 ...(isThinkingLevel(body.thinking) ? { thinking: body.thinking } : {}),
                 ...(typeof body.systemPrompt === "string" ? { systemPrompt: body.systemPrompt } : {}),
                 ...(Array.isArray(body.tools) ? { tools: body.tools } : {}),
@@ -91,13 +171,13 @@ async function handleSideQueryBody(req, res, url, ctx, miss) {
                     sendJson(res, 200, result);
             }
             catch (e) {
-                // 400 仅限 core 前置校验的**已知形**(messages 空我们已前拦;模型解析两句是 roles.ts 的稳定文案);
-                // 其余异常=server/adapter/config 缺陷,走 500(可告警、可重试语义)。stream 后错误按契约进
-                // result.errorMessage 不 throw;断连 abort 的抛出无人收,writableEnded/aborted 双判后静默。
+                // 400 仅限 core 前置校验的**已知形**;其余异常=server/adapter/config 缺陷,走 500(可告警、可重试
+                // 语义)。stream 后错误按契约进 result.errorMessage 不 throw;断连 abort 的抛出无人收,
+                // writableEnded/aborted 双判后静默。
                 deps.metrics?.inc?.("side_query_total", { result: "error" });
                 if (!res.writableEnded && !ac.signal.aborted) {
                     const m = msg(e);
-                    const isValidation = /^Unknown model ref |^No model for role |requires a non-empty messages array/.test(m);
+                    const isValidation = isCorePreflightValidationError(m);
                     // B7:机器码随状态码同分——已知前置校验形=`request.field_invalid`(客户端可改请求),其余=`internal.error`。
                     sendError(res, isValidation ? 400 : 500, isValidation ? "request.field_invalid" : "internal.error", redactSecrets(m));
                 }

package/dist/http/routes/workflows.js

@@ -108,12 +108,27 @@ async function handleWorkflowsReadBody(req, res, url, ctx, miss) {
             const jOffset = Math.max(0, Number(jq.get("offset") ?? 0) || 0);
             const MAX_ROW_BYTES = 64 * 1024;
             const firstLine = (t) => (t ? redactSecrets(t.split("\n")[0].slice(0, 300)) : undefined);
+            const MAX_RESULT_CHARS = 2000;
+            // A-002.6(披露双标,P1):>64KiB 的行诚实标 `truncated`/`resultBytes`(下方两臂),而 2000 字符~
+            // 64KiB 之间的行此前被 `slice(0, 2000)` **静默**截断 —— 同一个响应数组里一行说得出「我被截了」、
+            // 另一行说不出,消费者也无从区分「结果正好 2000 字」与「结果被截到 2000 字」。
+            // 🔴 键刻意**不复用** `truncated`:兄弟臂的 `truncated:true` 语义是「整行没内容,只有尺寸存根」,
+            //    盖到一行有内容的行上就是把兄弟臂的判别位改义(按它分支的消费者会把有内容的行当空存根)。
+            //    `resultTruncated`/`resultChars` 描述的是 `result` **这个字段**,无歧义。原始长度量的是
+            //    redact 之前的字符数(与兄弟臂 `resultBytes` 同精神,基准不同故不同名)。
+            // ⚠️ wire 记账:SDK spec 的 `WorkflowJournalEntry` 是 `additionalProperties: false`,两枚 additive
+            //    键需要 sema-sdk spec/openapi.yaml 同源补声明(SDK 件另走)。
             const projectResult = (callKey, r) => ({
                 callKey,
                 ordinal: callKeyOrdinal(callKey),
                 status: r.status,
                 ...(r.errorMessage ? { error: firstLine(r.errorMessage) } : {}),
-                ...(r.result ? { result: redactSecrets(r.result.slice(0, 2000)) } : {}),
+                ...(r.result
+                    ? {
+                        result: redactSecrets(r.result.slice(0, MAX_RESULT_CHARS)),
+                        ...(r.result.length > MAX_RESULT_CHARS ? { resultTruncated: true, resultChars: r.result.length } : {}),
+                    }
+                    : {}),
                 ...(r.stats ? { tokens: r.stats.tokens, turns: r.stats.turns } : {}),
             });
             const js = deps.workflowJournalStore;

package/dist/http/server.js

@@ -18,7 +18,7 @@ import {} from "../orchestration/workflow-agent-steer.js";
 import { emitPendingWorkflowCompletions, taskNotificationInboxEntry, taskNotificationStreamKey, NotifiedKeys } from "../orchestration/workflow-completion-inbox.js";
 import { fleetRunPublisher, fleetRunLabels, fleetRunResiduals, isFleetAgentTerminalNotification } from "../fleet/fleet-bus.js";
 import { defaultSubagentTailBus, projectTailFrame } from "../fleet/subagent-tail-bus.js";
-import { createApprovalCardEmitter, resolveApprovalLeg, resolveStreamApprovalGate } from "../tool-approval.js";
+import { createApprovalCardEmitter, isApprovalGateKind, resolveApprovalLeg, resolveStreamApprovalGate } from "../tool-approval.js";
 import {} from "../observability/rate-limit.js";
 import { withPrincipal } from "../observability/principal-context.js";
 import { turnEndEventData, contextUsageEventData, toolStartEventData, toolEndEventData, taskProgressEventData, taskNotificationEventData, compactedEventData, diagnosticsEventData, brainStatusEventData, steeringInjectedEventData, compactionOutcomeEventData, workspaceChangedEventData, wiringManifestEventData, humanInputEventData, appendModelUsageDelta, appendPromptManifest, attachModelUsage } from "../trace/project.js";
@@ -1322,9 +1322,9 @@ export function createHttpServer(rawDeps) {
         // 200 真跑完却拿不到 taskId、run 行永停 failed(账本与现实分叉)。这里 pre-CAS 纯拒绝:不动 checkpoint、
         // 不动 run 行、不烧模型腿,与另外两条腿的守卫同姿势(core 的 gate-match 仍是 fail-closed 兜底)。
         // ⚠️ 门放在 parked 赎回腿**之前**:赎回腿同样只铸 policy_ask outcome,错门 cp 在那条链上只会更深地炸。
-        // D-D SLA deny-sweep 不受影响:它的取行查询本就只选 gate_kind IN ('human','irreversible_ask')。
+        // D-D SLA deny-sweep 不受影响:它的取行查询本就只选 gate_kind ∈ APPROVAL_GATE_KINDS(tool-approval.ts 单一属主)。
         const decideGateKind = cp.gate?.kind;
-        if (decideGateKind !== "human" && decideGateKind !== "irreversible_ask") {
+        if (!isApprovalGateKind(decideGateKind)) { // A-002.1 单一属主
             // [2400] HITL-6(clay 裁 2026-08-03,不做兼容):补机读指路——与 [2255]① 的 409 材料同形
             // (pendingGate{kind, decidePath},resumeEntryForGate 单源表),客户端凭 decidePath 直达对的
             // resume 入口,不再解析人话文案。taskId 源=cp.sourceTaskId;缺席 ⇒ 只带 kind,诚实不铸假路径。
@@ -1406,8 +1406,8 @@ export function createHttpServer(rawDeps) {
         // escaping HttpError here was (a) attributed to the OPERATOR's /decide request as a bare 400/403 — undiagnosable
         // from that contract — and (b) swallowed by the D-D SLA deny-sweep's catch, silently failing EVERY tick. Fold it
         // into a typed 409 result instead: the operator sees "this parked task is blocked by a policy change" (retry
-        // after the policy is restored, or let terminal_at abort it); the sweep skips the row this tick (retried next
-        // tick, terminal_at backstop — its documented per-call-failure semantics).
+        // after the policy is restored, or let terminal_at_ms abort it); the sweep skips the row this tick (retried next
+        // tick, terminal_at_ms backstop — its documented per-call-failure semantics).
         let spec;
         try {
             spec = await deps.resolveSpec({ ...ctx.body, resumeAt: undefined }, req, auth);
@@ -2651,7 +2651,7 @@ export function createHttpServer(rawDeps) {
      * (graceful; vs the abort the reaper's expire() gives resource_limit/needs_review). Reuses resumeCheckpoint,
      * so the markResuming CAS makes it idempotent across replicas (one replica wins each resume) and the parked
      * run row is driven correctly. A per-call failure (e.g. a redeployed scenario) is swallowed → the row stays
-     * pending and is retried next tick, with the terminal_at backstop as the eventual abort if the deny never
+     * pending and is retried next tick, with the terminal_at_ms backstop as the eventual abort if the deny never
      * succeeds. Bounded per tick by the store query's LIMIT. Wired into main.ts's reaper.
      */
     async function denyExpiredApprovals(now) {
@@ -2659,7 +2659,7 @@ export function createHttpServer(rawDeps) {
         if (!cs)
             return;
         const expired = await cs.listExpiredApprovalGates(now).catch(() => []);
-        // [1591] 候裁③ 静默臂:parked 后台子代的过期 cp 不走 sweep 的重活赎回(deadline→terminal_at 窗内
+        // [1591] 候裁③ 静默臂:parked 后台子代的过期 cp 不走 sweep 的重活赎回(deadline→terminal_at_ms 窗内
         // 每行每 tick 一条 warn 的噪声源)——其收割属 reaper 的 expire+reconcileParkedAgents 车道。判别在
         // resume 尝试之前做(省掉注定 409 的整条 ctx/resolveSpec 重建尝试;代价=每过期行两次店读,过期集
         // 本就被店查询 LIMIT 界住);命中聚合为单条 info 留痕。判别自身故障 ⇒ 按非 parked 处理(保留 warn,
@@ -2684,7 +2684,7 @@ export function createHttpServer(rawDeps) {
         for (const { sessionId } of expired) {
             // 对抗评审 2026-07-11: log the swallow — a per-tick failure retried forever (e.g. a policy change now folded
             // into a 409 by resumeCheckpoint, or a redeployed scenario) was fully silent; the row sat pending to its
-            // terminal_at with zero operator-visible signal. Behavior unchanged (skip + retry next tick), now diagnosable.
+            // terminal_at_ms with zero operator-visible signal. Behavior unchanged (skip + retry next tick), now diagnosable.
             if (await isParkedOwned(sessionId)) {
                 parkedSkipped += 1;
                 continue;

package/dist/index.d.ts

@@ -12,7 +12,7 @@ export { buildSessionAudit, type SessionAudit } from "./audit.js";
 export { createLogger, type Logger, type LogLevel } from "./observability/logger.js";
 export { Metrics, createMetrics, type Labels } from "./observability/metrics.js";
 export { RateLimiter, type RateDecision } from "./observability/rate-limit.js";
-export { GiteaClient, repoToolsFor, parseRepo, type RepoCoords } from "./capabilities/repo-tools.js";
+export { GiteaClient, GitHubClient, createRepoClient, GIT_API_KINDS, isGitApiKind, repoToolsFor, parseRepo, type GitApiKind, type RepoCoords, type RepoReadClient } from "./capabilities/repo-tools.js";
 export { nowTool } from "./capabilities/builtin-tools.js";
 export { createCouncilTool } from "./capabilities/code-review-council.js";
 export { loadSkills, skillsForScenario, type LoadedSkill } from "./capabilities/skills.js";

package/dist/index.js

@@ -17,7 +17,7 @@ export { buildSessionAudit } from "./audit.js";
 export { createLogger } from "./observability/logger.js";
 export { Metrics, createMetrics } from "./observability/metrics.js";
 export { RateLimiter } from "./observability/rate-limit.js";
-export { GiteaClient, repoToolsFor, parseRepo } from "./capabilities/repo-tools.js";
+export { GiteaClient, GitHubClient, createRepoClient, GIT_API_KINDS, isGitApiKind, repoToolsFor, parseRepo } from "./capabilities/repo-tools.js";
 export { nowTool } from "./capabilities/builtin-tools.js";
 export { createCouncilTool } from "./capabilities/code-review-council.js";
 export { loadSkills, skillsForScenario } from "./capabilities/skills.js";

package/dist/main.js

@@ -16,7 +16,7 @@ import { webSearchConfigFromEnv, createWebSearchBackend, setWebSearchBadPayloadO
 import { createAuthorizer, encodeCheckpointScope } from "./security.js";
 import { assertGateIntentServiceable, hasOperatorGateIntent } from "./approval.js";
 import { loadSkills } from "./capabilities/skills.js";
-import { GiteaClient } from "./capabilities/repo-tools.js";
+import { createRepoClient } from "./capabilities/repo-tools.js";
 import { buildScenarios, builtinScenarioDetails } from "./capabilities/scenarios.js";
 import { createHandsLaneRegistry, pickHandsRunner, withoutExecutionEnv } from "./capabilities/hands-lane.js";
 import { createLogger } from "./observability/logger.js";
@@ -570,7 +570,7 @@ async function main() {
     // 解析搬到 boot/config-center.ts(逐字)。⚠️ 位置即契约:loadSkills 之后、buildScenarios 之前 ——
     // LKG 落盘点必须晚于 skill 正文装载(F7/codex R26),plugins 让位判据要求 plugins 晚于 center 直发 skills。
     skills = await configCenter.applyCenterCapabilities(skills);
-    const repoClient = config.gitApiBaseUrl ? new GiteaClient(config.gitApiBaseUrl, config.gitApiToken) : undefined;
+    const repoClient = config.gitApiBaseUrl ? createRepoClient(config.gitApiKind, config.gitApiBaseUrl, config.gitApiToken) : undefined;
     // CC-parity: deployment-injected WebSearch backend (the leg core leaves open). Absent WEB_SEARCH_PROVIDER →
     // undefined → the default scenario doesn't assemble the WebSearch tool. The API key stays in the backend closure.
     const webSearchCfg = webSearchConfigFromEnv();

package/dist/memory-scope.d.ts

@@ -1,5 +1,16 @@
 import { FileMemoryEngineBackend } from "@sema-agent/core";
 import type { ServiceConfig } from "./config-types.js";
+/** 前缀词表本体(供门/诊断读;判定一律走 {@link isV2ScopeKey},别在别处重写 startsWith 链)。 */
+export declare const V2_SCOPE_PREFIXES: readonly string[];
+/**
+ * 一个 scope 键是否带 v2 typed 前缀。
+ *
+ * ⚠️ 判据刻意停在**前缀**层,不升级成 core 的 `parseScopeKey`:后者对「带可识别前缀但结构坏」的键
+ * 是 fail-loud 抛错,而本谓词的两个调用点都只是在决定「要不要挂 v2 标 / 要不要再包一层」——把抛点
+ * 挪到这里会把 core 的校验时机整体前移(行为面改动,不在本条案的射程内)。坏键仍由 core 在它自己的
+ * 校验点 fail-loud。
+ */
+export declare function isV2ScopeKey(key: string): boolean;
 /** Resolve the memory scope for a request (design/138 S1 — the file-based memory engine is the only plane).
  *
  *  SINGLE-USER (REQUIRE_PRINCIPAL !== "true"): ONE shared scope — `config.memoryScope` (default "local"),
@@ -11,6 +22,11 @@ import type { ServiceConfig } from "./config-types.js";
  *  fail-closed. The engine's file basement carries NO tenant isolation (one shared directory tree), so
  *  handing tenants per-principal scopes over it would be a cross-tenant bleed surface; until a
  *  tenant-isolated backend exists, multi-tenant memory is off by construction. */
+/** R5(批γ):memory scope 列宽(两方言 VARCHAR(190) 同宽)。principal 上限 190 **字符**在
+ *  security.ts 把身份轴守住了,但 `formatUserScope`/`formatProjScope` 的段编码(百分号转义)会
+ *  **膨胀**——非 ASCII principal 编码后可超列宽,此前落裸 SQL 错。产出处响亮拒,错误可分类。 */
+export declare const MEMORY_SCOPE_COLUMN_CHARS = 190;
+export declare function assertMemoryScopeWidth(scope: string): void;
 export declare function memoryScopeFor(config: ServiceConfig, principal?: string, projectId?: string): string | undefined;
 /**
  * N0 (通宵测试 2026-07-09,三重坐实 e2b+kata+代码): the file memory engine (core design/138) materializes and

package/dist/memory-scope.js

@@ -5,6 +5,34 @@
 // "exports" only ever exposed "." and "./main" — dist/security.js was never a reachable deep-import path).
 import { join } from "node:path";
 import { FileMemoryEngineBackend, resolveMemoryEngineRoot, deriveControlPlaneDir, formatUserScope, formatProjScope } from "@sema-agent/core";
+/**
+ * design/142 §1.2 的 v2 typed scope-key 前缀表 —— **单一属主**(A-002.4:`config.ts` 的
+ * MEMORY_SYNC_SCOPE 派生处曾有一份逐字副本,两处咬合用途不同[盖 v2 契约标 vs 判要不要再包一层
+ * `formatUserScope`],但判据必须是同一份,否则 core 加第五种 typed 前缀时两处各自漂)。
+ *
+ * 🔴 表按 core 的 {@link ParsedScopeKey} 判别词**穷举**:`Record<Exclude<kind,"legacy">, …>` 少一格
+ * 编译红、多一格也编译红 —— core 新增/改名一种 typed kind,本表在编译期就先红,而不是等某个运行期
+ * 分支静默走错。(`legacy` 排除在外正是本谓词要判的反面:无可识别前缀 = 不透明旧键。)
+ */
+const V2_SCOPE_PREFIX_BY_KIND = {
+    user: "user:",
+    org: "org:",
+    proj: "proj:",
+    userproj: "userproj:",
+};
+/** 前缀词表本体(供门/诊断读;判定一律走 {@link isV2ScopeKey},别在别处重写 startsWith 链)。 */
+export const V2_SCOPE_PREFIXES = Object.freeze(Object.values(V2_SCOPE_PREFIX_BY_KIND));
+/**
+ * 一个 scope 键是否带 v2 typed 前缀。
+ *
+ * ⚠️ 判据刻意停在**前缀**层,不升级成 core 的 `parseScopeKey`:后者对「带可识别前缀但结构坏」的键
+ * 是 fail-loud 抛错,而本谓词的两个调用点都只是在决定「要不要挂 v2 标 / 要不要再包一层」——把抛点
+ * 挪到这里会把 core 的校验时机整体前移(行为面改动,不在本条案的射程内)。坏键仍由 core 在它自己的
+ * 校验点 fail-loud。
+ */
+export function isV2ScopeKey(key) {
+    return V2_SCOPE_PREFIXES.some((prefix) => key.startsWith(prefix));
+}
 /** Resolve the memory scope for a request (design/138 S1 — the file-based memory engine is the only plane).
  *
  *  SINGLE-USER (REQUIRE_PRINCIPAL !== "true"): ONE shared scope — `config.memoryScope` (default "local"),
@@ -16,6 +44,16 @@ import { FileMemoryEngineBackend, resolveMemoryEngineRoot, deriveControlPlaneDir
  *  fail-closed. The engine's file basement carries NO tenant isolation (one shared directory tree), so
  *  handing tenants per-principal scopes over it would be a cross-tenant bleed surface; until a
  *  tenant-isolated backend exists, multi-tenant memory is off by construction. */
+/** R5(批γ):memory scope 列宽(两方言 VARCHAR(190) 同宽)。principal 上限 190 **字符**在
+ *  security.ts 把身份轴守住了,但 `formatUserScope`/`formatProjScope` 的段编码(百分号转义)会
+ *  **膨胀**——非 ASCII principal 编码后可超列宽,此前落裸 SQL 错。产出处响亮拒,错误可分类。 */
+export const MEMORY_SCOPE_COLUMN_CHARS = 190;
+export function assertMemoryScopeWidth(scope) {
+    if (scope.length > MEMORY_SCOPE_COLUMN_CHARS) {
+        throw new Error(`memory scope exceeds ${MEMORY_SCOPE_COLUMN_CHARS} characters after segment encoding (the scope column width ` +
+            `both SQL dialects pin); got ${scope.length} — use a shorter principal/projectId (non-ASCII characters expand ~9x when encoded)`);
+    }
+}
 export function memoryScopeFor(config, principal, projectId) {
     if (config.requirePrincipal === true) {
         // S3-TOB(设计 §1.3):multi-tenant lights up ONLY on a DB backend (scope column = tenant
@@ -34,7 +72,9 @@ export function memoryScopeFor(config, principal, projectId) {
         if (config.memoryEngineBackend === "pg" || config.memoryEngineBackend === "tidb") {
             if (!principal)
                 return undefined;
-            return projectId ? formatProjScope(principal, projectId) : formatUserScope(principal);
+            const scope = projectId ? formatProjScope(principal, projectId) : formatUserScope(principal);
+            assertMemoryScopeWidth(scope); // R5:编码膨胀在产出处接住,不落 store 裸错
+            return scope;
         }
         return undefined; // file backend: dark, fail-closed (no tenant isolation in the file engine)
     }
@@ -113,7 +153,7 @@ originPolicy) {
     // OPERATOR's center-registry declaration (config.projects — 登记簿说明其形态=v2 scope 键串),so the
     // prefix is a self/operator-produced marker, never a guess about caller data; a legacy opaque scope
     // (single-user config.memoryScope) with no defaultScopes stays contract-less byte-identical.
-    const isV2 = (k) => k.startsWith("user:") || k.startsWith("org:") || k.startsWith("proj:") || k.startsWith("userproj:");
+    const isV2 = isV2ScopeKey; // A-002.4:词表单一属主(见文件顶部 V2_SCOPE_PREFIX_BY_KIND)
     // 142-S4 defaultScopes 种子(config.projects[projectId].defaultScopes):额外的 READ 层(去重、去 scope
     // 自身、去空串;保 center 声明顺序)。写路由不变:core normalizeMemorySpec 的 writeScope 缺省=scopes 的
     // 最后一层,所以带种子时必须 EXPLICIT 钉 writeScope=派生 scope(否则 harvest 会写进登记簿的最后一个默认

package/dist/plugins/checkpoint-store-sql.d.ts

@@ -4,7 +4,7 @@ import { type Checkpoint, type CheckpointGate, type CheckpointState, type Checkp
 import { type SqlDriver } from "./sql-driver.js";
 /**
  * design/80 D-1 (§3 invariant #3 — crash-safe reaper backstop): an ABSOLUTE upper bound on a pending
- * checkpoint's lifetime, stamped at put() into `terminal_at` INDEPENDENT of the per-approval `deadline`. The
+ * checkpoint's lifetime, stamped at put() into `terminal_at_ms` INDEPENDENT of the per-approval `deadline`. The
  * SLA-timer (D-D) does the fine, per-gate-kind resolve-deny; THIS coarse backstop ensures even a pending row
  * with a NULL `deadline` (no approval TTL configured) is eventually GC'd if the SLA service dies — closing a
  * forever-leak of a never-resolved suspension (the current `reap`/`reapExpired` only catch non-NULL deadlines).
@@ -13,9 +13,9 @@ import { type SqlDriver } from "./sql-driver.js";
  */
 export declare const TERMINAL_BACKSTOP_MS: number;
 /**
- * design/80 D-D (adversarial fix): the crash-safe `terminal_at` backstop must fall STRICTLY AFTER any SLA
- * `deadline`, never AT it. `terminal_at = max(createdAt+backstop, deadline)` made the two coincide whenever an
- * operator tuned APPROVAL_TERMINAL_BACKSTOP_MS at/below the SLA — and reapExpired's terminal_at-branch (which
+ * design/80 D-D (adversarial fix): the crash-safe `terminal_at_ms` backstop must fall STRICTLY AFTER any SLA
+ * `deadline`, never AT it. `terminal_at_ms = max(createdAt+backstop, deadline)` made the two coincide whenever an
+ * operator tuned APPROVAL_TERMINAL_BACKSTOP_MS at/below the SLA — and reapExpired's terminal_at_ms-branch (which
  * has NO gate_kind filter) then abort-EXPIRED a human/irreversible_ask gate in the SAME tick the deny-sweep
  * wanted to gracefully DENY it, racing it away. Adding this grace to the deadline term guarantees the deny-sweep
  * at least this window of clean ticks before the absolute backstop can fire. Far smaller than the backstop, so
@@ -252,8 +252,8 @@ export declare class SqlCheckpointStore implements CheckpointStore {
     /**
      * GLOBAL sweep for the service's per-replica TTL reaper (expiry isn't tenant-
      * sensitive — only `resolve` is scoped). Idempotent across replicas (DB serializes; no election). Returns count.
-     * Called with `cutoff = Date.now()` (deadline/terminal_at are ABSOLUTE epoch-ms), so it expires any pending row
-     * whose per-approval `deadline` OR its design/80 D-1 §3-inv#3 `terminal_at` crash-safe backstop has passed —
+     * Called with `cutoff = Date.now()` (deadline/terminal_at_ms are ABSOLUTE epoch-ms), so it expires any pending row
+     * whose per-approval `deadline` OR its design/80 D-1 §3-inv#3 `terminal_at_ms` crash-safe backstop has passed —
      * the latter closes the forever-leak of a pending row with a NULL `deadline` (no approval TTL was configured).
      *
      * design/80 D-D: the deadline-branch EXPIRES (≈ abort) every kind EXCEPT a tool-approval human/irreversible_ask
@@ -262,7 +262,7 @@ export declare class SqlCheckpointStore implements CheckpointStore {
      * AskUserQuestion ALSO mints gate.kind='human' (no question-specific kind in core) — but DENYING a question is
      * incoherent (the model gets a "denied" tool-result, not an answer), so it is carved BACK INTO the expire path
      * (COALESCE(tool_name,'')='AskUserQuestion') to abort-expire on timeout instead. Legacy rows (gate_kind NULL)
-     * stay on the expire path. The terminal_at-branch is the crash-safe backstop for ANY kind (incl. a human gate
+     * stay on the expire path. The terminal_at_ms-branch is the crash-safe backstop for ANY kind (incl. a human gate
      * whose deny-resume keeps failing) — it always abort-expires past the absolute cap (which is now STRICTLY after
      * the deadline, so it never races the deny-sweep at the deadline instant).
      */
@@ -291,7 +291,7 @@ export declare class SqlCheckpointStore implements CheckpointStore {
      * (gate kind + risk severity + budget spent + deadline per suspended task), no N+1 `get`s. The projection is
      * core's shared {@link summarizeCheckpoint} run over the persisted blob (the `checkpoint` column = the same full
      * {@link Checkpoint} `get()` parses), so this stays byte-identical to core's InMemory/Pg/File impls. Order =
-     * created_at ASC; callers (the inbox/scheduler) sort by severity. The COLUMN `status` is authoritative (the blob
+     * created_at_ms ASC; callers (the inbox/scheduler) sort by severity. The COLUMN `status` is authoritative (the blob
      * is the suspend-time snapshot), so it overrides the blob's status before the summary is derived.
      *
      * LIMIT bounds the fan-out (review w16yqkkxv): a triage view never needs more than a few — 500 is a generous
@@ -309,7 +309,7 @@ export declare class SqlCheckpointStore implements CheckpointStore {
      *
      * 「这条 PARKING 的 ask 究竟 park 成了哪张 checkpoint?」的唯一读法。为什么不是「按 session 翻历史页」:
      * 分页宽读会漏匹配,而漏匹配在收敛器那侧的后果是**假阴性 ⇒ 落一条不可逆的 DENIED**。所以这里改成
-     * 谓词精确查——`(scope, session_id, tool_call_id, created_at ≥ sinceMs)` 这组条件下的行数天然极小,
+     * 谓词精确查——`(scope, session_id, tool_call_id, created_at_ms ≥ sinceMs)` 这组条件下的行数天然极小,
      * 一次全量返回,结构上没有分页假阴性。
      *
      * 三条口径,逐条都是判据: