@sema-agent/server 7.8.1 → 7.10.0

package/USAGE.md

@@ -413,6 +413,12 @@ curl -s http://<host>:8090/v1/runs/<taskId> -H 'x-agent-principal: user:42'   #
 > 不是裸主机名——服务端直接拼 `${GIT_API_BASEURL}/api/v1/...` 发请求,裸 `git.example.com` 会拼出非法 URL 而 fetch 失败。
 > 末尾不要带 `/`,也不要把 `/api/v1` 写进来。
 
+> **`GIT_API_KIND`(7.10.0 起)**:Git host 方言,闭集 `gitea`(缺省)/ `github`。GitHub 托管仓
+> (github.com 或 GHE)设 `GIT_API_KIND=github`,此时 `GIT_API_BASEURL` 写 **API 根**(github.com 用
+> `https://api.github.com`;GHE 用 `https://ghe.example.com/api/v3`),token 用 fine-grained PAT
+> (仅 contents/pull-requests 只读)。未知词拒启;`GIT_API_BASEURL` 指向 github.com 族而 kind 仍是
+> gitea 也拒启并指路(Gitea 形状对 GitHub 恒 404,启动即报优于运行时逐调用 404)。
+
 > **升级注记(7.7.0)**:本版起 `code-review` / `scan` / `team` / `toolset: repo-readonly|none` 的场景改跑
 > 无执行环境的引擎。**升级前**若还有这些场景的 durable 挂起任务(需同时满足:配了 `REMOTE_EXEC`、开了
 > `DURABLE_APPROVAL`、任务已 park),它们在新版上续跑会以 409 `checkpoint.unsupported_version` 响亮失败

package/dist/approval-reconciler.d.ts

@@ -167,7 +167,7 @@ export declare function isAncestorFoldMint(ask: AskRow): boolean;
  *    走到 hash 这一层才把缺席记成**单铸** `single_mint`(见 {@link GateMatchOutcome})。
  *
  * 多候选时的取舍:优先 `status === "pending"`(活着的那张 gate),否则取最早的一条(读口按
- * `created_at ASC` 返回)。两者都满足全部硬谓词,选谁都不会错配;取 pending 只是让 `PARKED` 行落到
+ * `created_at_ms ASC` 返回)。两者都满足全部硬谓词,选谁都不会错配;取 pending 只是让 `PARKED` 行落到
  * 一个还能被 resume 的坐标上,对壳更有用。
  */
 export declare function classifyGateMatch(ask: AskRow, candidates: readonly CheckpointAskCandidate[]): GateMatchOutcome;

package/dist/approval-reconciler.js

@@ -32,15 +32,23 @@ const RECONCILE_STORE_TIMEOUT_MS = 10_000;
  */
 const RECONCILE_SEGMENT_BUDGET_MS = 30_000;
 /** 给一次读/写套墙钟上限(超时以 Error 拒绝,由 per-row catch 接住)。定时器 `unref`,绝不持住进程;
- *  竞速输的那一路由 `Promise.race` 自己的 handler 接住,不会变成 unhandled rejection。 */
+ *  竞速输的那一路由 `Promise.race` 自己的 handler 接住,不会变成 unhandled rejection。
+ *
+ *  A-002.10:竞速一结束就 `clearTimeout`。`unref` 只保证不吊住进程退出,**不**回收定时器本身——本函数在
+ *  逐行串行的 `runOnce` 里每行要走 1~6 次,不清就是「每行 1~6 只挂满 {@link RECONCILE_STORE_TIMEOUT_MS}」
+ *  的累积(batchLimit 默认 200 ⇒ 一轮几百只带闭包的定时器)。`finally` 对成功/失败两路都清。 */
 function withDeadline(op, label, timeoutMs = RECONCILE_STORE_TIMEOUT_MS) {
+    let timer;
     return Promise.race([
         op,
         new Promise((_resolve, reject) => {
-            const t = setTimeout(() => reject(new Error(`approval reconcile ${label} timed out after ${timeoutMs}ms`)), timeoutMs);
-            t.unref?.();
+            timer = setTimeout(() => reject(new Error(`approval reconcile ${label} timed out after ${timeoutMs}ms`)), timeoutMs);
+            timer.unref?.();
         }),
-    ]);
+    ]).finally(() => {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    });
 }
 /**
  * 这只 ask 是不是**祖先冻结 approver 层**在委派 fold 中途铸的那一份(#168 件1④,黑板 [2912]③)。
@@ -76,7 +84,7 @@ export function isAncestorFoldMint(ask) {
  *    走到 hash 这一层才把缺席记成**单铸** `single_mint`(见 {@link GateMatchOutcome})。
  *
  * 多候选时的取舍:优先 `status === "pending"`(活着的那张 gate),否则取最早的一条(读口按
- * `created_at ASC` 返回)。两者都满足全部硬谓词,选谁都不会错配;取 pending 只是让 `PARKED` 行落到
+ * `created_at_ms ASC` 返回)。两者都满足全部硬谓词,选谁都不会错配;取 pending 只是让 `PARKED` 行落到
  * 一个还能被 resume 的坐标上,对壳更有用。
  */
 export function classifyGateMatch(ask, candidates) {

package/dist/boot/execution-env.js

@@ -222,6 +222,12 @@ export function createExecutionEnv(ctx) {
             ...(config.remoteExec.dockerHost ? { dockerHost: config.remoteExec.dockerHost } : {}),
             ...(config.remoteExec.memory ? { memory: config.remoteExec.memory } : {}),
             ...(config.remoteExec.cpus != null ? { cpus: config.remoteExec.cpus } : {}),
+            // A-002.7: the two sandbox-hardening knobs were parsed by loadConfig and honored by the adapter, but this
+            // call site dropped them — so DOCKER_PIDS_LIMIT always resolved to the adapter's `?? 512` default and
+            // DOCKER_DROP_CAPS never emitted `--cap-drop ALL`. Absent stays absent (the adapter's defaults are the
+            // unconfigured shape); only a SET knob rides, same additive form as the siblings above.
+            ...(config.remoteExec.pidsLimit != null ? { pidsLimit: config.remoteExec.pidsLimit } : {}),
+            ...(config.remoteExec.dropAllCaps ? { dropAllCaps: true } : {}),
             ...(config.remoteExec.network ? { network: config.remoteExec.network } : {}),
             ...(config.remoteExec.commandTimeoutMs != null ? { commandTimeoutMs: config.remoteExec.commandTimeoutMs } : {}),
             ...(config.remoteExec.env ? { env: config.remoteExec.env } : {}),

package/dist/boot/reapers.js

@@ -244,12 +244,12 @@ export function startReapers(ctx) {
             .then(reapCount("runs_reaped_total", { kind: "stale" }))
             .then(() => runsReapStaleGuard.onSuccess(), runsReapStaleGuard.onError);
         // Durable F4 (design/45) + design/80 §3 inv#3 crash-safe backstop: CAS-expire checkpoints past their
-        // deadline OR their absolute terminal_at backstop (≈ deny), then fail the suspended run rows whose
+        // deadline OR their absolute terminal_at_ms backstop (≈ deny), then fail the suspended run rows whose
         // checkpoint was thereby expired (release task_active = unlock the session). These run EVERY tick,
-        // REGARDLESS of APPROVAL_TIMEOUT_SEC — terminal_at (stamped at put, never before an explicit deadline)
+        // REGARDLESS of APPROVAL_TIMEOUT_SEC — terminal_at_ms (stamped at put, never before an explicit deadline)
         // bounds even a NULL-deadline pending checkpoint, so the backstop is the always-on safety net (it was
         // inert when nested under the approvalTimeoutSec>0 guard — adversarial finding). The run-row half is
-        // checkpoint-STATE-driven (not a uniform timer) so it aligns with the per-row terminal_at. Global +
+        // checkpoint-STATE-driven (not a uniform timer) so it aligns with the per-row terminal_at_ms. Global +
         // idempotent across replicas, no election.
         if (checkpointStore) {
             // 轴A #5 注释落档(1.254):core CheckpointStore.reap 契约把弃置臂的 unpin 义务派给部署 reaper——

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

@@ -13,8 +13,42 @@ export interface RepoCoords {
 }
 /** Parse `owner/name` or a repo URL (e.g. https://git.example.com/some-org/some-repo.git). */
 export declare function parseRepo(input: string): RepoCoords;
+import type { GitApiKind } from "../git-api-kind.js";
+export { GIT_API_KINDS, isGitApiKind, type GitApiKind } from "../git-api-kind.js";
+/** The read-only surface the repo tools are built over — one implementation per Git-host dialect. */
+export interface RepoReadClient {
+    defaultBranch(coords: RepoCoords): Promise<string>;
+    tree(coords: RepoCoords, ref: string): Promise<string[]>;
+    readFile(coords: RepoCoords, path: string, ref: string): Promise<string>;
+    pullDiff(coords: RepoCoords, index: number): Promise<string>;
+}
+export declare function createRepoClient(kind: GitApiKind, baseUrl: string, token?: string, fetchImpl?: typeof fetch): RepoReadClient;
 /** Thin read-only Gitea API client. Built once at startup; bound to a repo per task. */
-export declare class GiteaClient {
+export declare class GiteaClient implements RepoReadClient {
+    private readonly baseUrl;
+    private readonly token?;
+    private readonly fetchImpl;
+    constructor(baseUrl: string, token?: string | undefined, fetchImpl?: typeof fetch);
+    private api;
+    defaultBranch({ owner, repo }: RepoCoords): Promise<string>;
+    tree(coords: RepoCoords, ref: string): Promise<string[]>;
+    readFile(coords: RepoCoords, path: string, ref: string): Promise<string>;
+    pullDiff(coords: RepoCoords, index: number): Promise<string>;
+}
+/**
+ * Thin read-only GitHub (github.com / GHE) API client — same four-call surface as `GiteaClient`.
+ *
+ * Dialect differences (each one is why `GiteaClient` alone 404s against GitHub):
+ *  - base URL is the API root itself (`https://api.github.com`, GHE `https://ghe.example/api/v3`) —
+ *    no `/api/v1` prefix is appended;
+ *  - auth is `Authorization: Bearer <token>` (Gitea uses `token <token>`);
+ *  - a PR's unified diff comes from `/pulls/{n}` via `Accept: application/vnd.github.v3.diff`
+ *    (Gitea uses a `.diff` URL suffix);
+ *  - the tree API has no `per_page` cap — GitHub returns up to its own limit and reports overflow via
+ *    `truncated`; we additionally cap client-side at MAX_TREE_ENTRIES so the model-facing bound is the
+ *    same for both dialects.
+ */
+export declare class GitHubClient implements RepoReadClient {
     private readonly baseUrl;
     private readonly token?;
     private readonly fetchImpl;
@@ -26,5 +60,5 @@ export declare class GiteaClient {
     pullDiff(coords: RepoCoords, index: number): Promise<string>;
 }
 /** Build the read-only repo tool set bound to one repo (cheap per-task closure; the client is shared). */
-export declare function repoToolsFor(client: GiteaClient, coords: RepoCoords): ToolSpec[];
+export declare function repoToolsFor(client: RepoReadClient, coords: RepoCoords): ToolSpec[];
 //# sourceMappingURL=repo-tools.d.ts.map

package/dist/capabilities/repo-tools.js

@@ -1,4 +1,5 @@
 import { Type } from "typebox";
+import { z } from "zod";
 /** Parse `owner/name` or a repo URL (e.g. https://git.example.com/some-org/some-repo.git). */
 export function parseRepo(input) {
     const s = input.trim().replace(/\.git$/, "");
@@ -13,6 +14,43 @@ const MAX_FILE_BYTES = 96 * 1024;
 const MAX_TREE_ENTRIES = 2000;
 /** Bound each Git-host call so a slow/hung host can't pin a review lens to its whole deadline. */
 const REQUEST_TIMEOUT_MS = 15_000;
+export { GIT_API_KINDS, isGitApiKind } from "../git-api-kind.js";
+/** Wire schemas for the Git-host responses we consume (both dialects share these shapes — Gitea copied
+ *  GitHub's). Boundary discipline(宪法 [2704] §2):no bare `as` on `.json()`. */
+const RepoInfoWire = z.looseObject({ default_branch: z.string().optional() });
+const TreeWire = z.looseObject({
+    tree: z.array(z.looseObject({ path: z.string(), type: z.string() })).optional(),
+    truncated: z.boolean().optional(),
+});
+const ContentsWire = z.looseObject({
+    content: z.string().optional().nullable(),
+    encoding: z.string().optional(),
+    type: z.string().optional(),
+});
+const PullMetaWire = z.looseObject({ changed_files: z.number().optional() });
+/** Shared guard: `encodeURIComponent` does NOT escape "." — a `..` segment survives the per-segment
+ *  encode and the WHATWG URL parser collapses it when `fetch` builds the request, letting a crafted
+ *  `path` climb out of `/repos/<owner>/<repo>/contents/` to any endpoint the read token can reach.
+ *  The tools are contractually bound to exactly one repo, so reject traversal before it hits fetch. */
+function pathSegmentsRejectingTraversal(path) {
+    const segments = path.split("/").filter(Boolean);
+    if (segments.some((s) => s === "..")) {
+        throw new Error(`invalid path "${path}" (".." segments are not allowed)`);
+    }
+    return segments;
+}
+export function createRepoClient(kind, baseUrl, token, fetchImpl = fetch) {
+    switch (kind) {
+        case "gitea":
+            return new GiteaClient(baseUrl, token, fetchImpl);
+        case "github":
+            return new GitHubClient(baseUrl, token, fetchImpl);
+        default: {
+            const never = kind;
+            throw new Error(`unknown gitApiKind ${String(never)}`);
+        }
+    }
+}
 /** Thin read-only Gitea API client. Built once at startup; bound to a repo per task. */
 export class GiteaClient {
     baseUrl;
@@ -36,12 +74,12 @@ export class GiteaClient {
         return res;
     }
     async defaultBranch({ owner, repo }) {
-        const info = (await (await this.api(`/repos/${owner}/${repo}`)).json());
+        const info = RepoInfoWire.parse(await (await this.api(`/repos/${owner}/${repo}`)).json());
         return info.default_branch || "main";
     }
     async tree(coords, ref) {
         const { owner, repo } = coords;
-        const body = (await (await this.api(`/repos/${owner}/${repo}/git/trees/${encodeURIComponent(ref)}?recursive=true&per_page=${MAX_TREE_ENTRIES}`)).json());
+        const body = TreeWire.parse(await (await this.api(`/repos/${owner}/${repo}/git/trees/${encodeURIComponent(ref)}?recursive=true&per_page=${MAX_TREE_ENTRIES}`)).json());
         const paths = (body.tree ?? []).filter((e) => e.type === "blob").map((e) => e.path);
         // The upstream API caps the listing at `per_page` and reports the overflow via `truncated` — it does
         // not report how many entries were left out. Surface that (same disclosure-marker family as
@@ -52,15 +90,8 @@ export class GiteaClient {
     }
     async readFile(coords, path, ref) {
         const { owner, repo } = coords;
-        // `encodeURIComponent` does NOT escape "." — so a `..` segment survives the per-segment encode and the
-        // WHATWG URL parser collapses it when `fetch` builds the request, letting a crafted `path` climb out of
-        // `/repos/<owner>/<repo>/contents/` to any endpoint the read token can reach (cross-repo / admin). The
-        // tools are contractually bound to exactly one repo (see header), so reject traversal before it hits fetch.
-        const segments = path.split("/").filter(Boolean);
-        if (segments.some((s) => s === "..")) {
-            throw new Error(`invalid path "${path}" (".." segments are not allowed)`);
-        }
-        const body = (await (await this.api(`/repos/${owner}/${repo}/contents/${segments.map(encodeURIComponent).join("/")}?ref=${encodeURIComponent(ref)}`)).json());
+        const segments = pathSegmentsRejectingTraversal(path);
+        const body = ContentsWire.parse(await (await this.api(`/repos/${owner}/${repo}/contents/${segments.map(encodeURIComponent).join("/")}?ref=${encodeURIComponent(ref)}`)).json());
         if (body.type !== "file" || body.content == null)
             throw new Error(`not a file: ${path}`);
         const text = body.encoding === "base64" ? Buffer.from(body.content, "base64").toString("utf8") : body.content;
@@ -75,6 +106,89 @@ export class GiteaClient {
         return text.length > MAX_FILE_BYTES * 4 ? text.slice(0, MAX_FILE_BYTES * 4) + "\n…[diff truncated]" : text;
     }
 }
+/**
+ * Thin read-only GitHub (github.com / GHE) API client — same four-call surface as `GiteaClient`.
+ *
+ * Dialect differences (each one is why `GiteaClient` alone 404s against GitHub):
+ *  - base URL is the API root itself (`https://api.github.com`, GHE `https://ghe.example/api/v3`) —
+ *    no `/api/v1` prefix is appended;
+ *  - auth is `Authorization: Bearer <token>` (Gitea uses `token <token>`);
+ *  - a PR's unified diff comes from `/pulls/{n}` via `Accept: application/vnd.github.v3.diff`
+ *    (Gitea uses a `.diff` URL suffix);
+ *  - the tree API has no `per_page` cap — GitHub returns up to its own limit and reports overflow via
+ *    `truncated`; we additionally cap client-side at MAX_TREE_ENTRIES so the model-facing bound is the
+ *    same for both dialects.
+ */
+export class GitHubClient {
+    baseUrl;
+    token;
+    fetchImpl;
+    constructor(baseUrl, token, fetchImpl = fetch) {
+        this.baseUrl = baseUrl;
+        this.token = token;
+        this.fetchImpl = fetchImpl;
+    }
+    async api(path, accept = "application/vnd.github+json") {
+        const headers = { accept, "x-github-api-version": "2022-11-28" };
+        if (this.token)
+            headers.authorization = `Bearer ${this.token}`;
+        const res = await this.fetchImpl(`${this.baseUrl.replace(/\/+$/, "")}${path}`, {
+            headers,
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        });
+        if (!res.ok)
+            throw new Error(`git api ${path} → HTTP ${res.status}`);
+        return res;
+    }
+    async defaultBranch({ owner, repo }) {
+        const info = RepoInfoWire.parse(await (await this.api(`/repos/${owner}/${repo}`)).json());
+        return info.default_branch || "main";
+    }
+    async tree(coords, ref) {
+        const { owner, repo } = coords;
+        const body = TreeWire.parse(await (await this.api(`/repos/${owner}/${repo}/git/trees/${encodeURIComponent(ref)}?recursive=1`)).json());
+        const paths = (body.tree ?? []).filter((e) => e.type === "blob").map((e) => e.path);
+        // Same disclosure-marker family as GiteaClient.tree: a capped listing must never read as the whole
+        // repo. Two cap sources here — upstream `truncated`, and our own client-side MAX_TREE_ENTRIES bound.
+        if (paths.length > MAX_TREE_ENTRIES) {
+            return [...paths.slice(0, MAX_TREE_ENTRIES), `…[truncated, tree has more than ${MAX_TREE_ENTRIES} entries]`];
+        }
+        return body.truncated
+            ? [...paths, `…[truncated, tree has more than ${MAX_TREE_ENTRIES} entries]`]
+            : paths;
+    }
+    async readFile(coords, path, ref) {
+        const { owner, repo } = coords;
+        const segments = pathSegmentsRejectingTraversal(path);
+        const body = ContentsWire.parse(await (await this.api(`/repos/${owner}/${repo}/contents/${segments.map(encodeURIComponent).join("/")}?ref=${encodeURIComponent(ref)}`)).json());
+        if (body.type !== "file" || body.content == null)
+            throw new Error(`not a file: ${path}`);
+        // GitHub 文档行为(codex F1 定谳):1–100 MB 文件走对象形返回 `content:"", encoding:"none"` ——
+        // content 非 null 过上面的门,非 base64 臂又会把空串当正文交出 = 「大文件被当空文件评审」的静默
+        // 完整性失败。显式臂响亮拒(本工具本地帽 96 KiB,>1 MB 内容也装不下,拒绝即诚实)。
+        if (body.encoding === "none") {
+            throw new Error(`file too large for the contents API: ${path} (GitHub returns encoding:"none" for files over 1 MB — this read tool cannot fetch it; review it via the PR diff or skip it)`);
+        }
+        const text = body.encoding === "base64" ? Buffer.from(body.content, "base64").toString("utf8") : body.content;
+        return text.length > MAX_FILE_BYTES
+            ? text.slice(0, MAX_FILE_BYTES) + `\n…[truncated, ${text.length - MAX_FILE_BYTES} more bytes]`
+            : text;
+    }
+    async pullDiff(coords, index) {
+        const { owner, repo } = coords;
+        // GitHub 在服务端静默截断 PR diff(300 文件 / 1 MB / 20k 行,文档行为;codex F2 定谳)——被截的
+        // 响应可能远小于本地帽,靠字节数判不出来。先取 PR 元数据拿 changed_files,与 diff 里实际出现的
+        // 文件数对账,少了就显式披露(上游截断与本地帽是两种截断,分开标)。
+        const meta = PullMetaWire.parse(await (await this.api(`/repos/${owner}/${repo}/pulls/${index}`)).json());
+        const res = await this.api(`/repos/${owner}/${repo}/pulls/${index}`, "application/vnd.github.v3.diff");
+        let text = await res.text();
+        const filesInDiff = (text.match(/^diff --git /gm) ?? []).length;
+        if (typeof meta.changed_files === "number" && filesInDiff < meta.changed_files) {
+            text += `\n…[upstream truncated: this diff covers ${filesInDiff} of ${meta.changed_files} changed files — GitHub caps PR diffs (300 files / 1 MB); review the remaining files individually]`;
+        }
+        return text.length > MAX_FILE_BYTES * 4 ? text.slice(0, MAX_FILE_BYTES * 4) + "\n…[diff truncated]" : text;
+    }
+}
 /** Build the read-only repo tool set bound to one repo (cheap per-task closure; the client is shared). */
 export function repoToolsFor(client, coords) {
     const ref = (r) => (r ? Promise.resolve(r) : client.defaultBranch(coords));

package/dist/capabilities/scenarios.d.ts

@@ -1,7 +1,7 @@
 import { type WebFetchConfig, type BackgroundAgentStore, type CheckpointStore, type PromptProvider, type Runner, type SkillSpec, type SubagentSpawnContext, type ToolSpec, type WebSearchConfig } from "@sema-agent/core";
 import type { Metrics } from "../observability/metrics.js";
 import type { Logger } from "../observability/logger.js";
-import { GiteaClient } from "./repo-tools.js";
+import { type RepoReadClient } from "./repo-tools.js";
 import { type LoadedSkill } from "./skills.js";
 import { type ScenarioHands } from "./hands-lane.js";
 /**
@@ -46,7 +46,7 @@ export interface ScenarioDeps {
     handslessSubRunner: Runner;
     model: string;
     skills: LoadedSkill[];
-    repoClient?: GiteaClient;
+    repoClient?: RepoReadClient;
     /** Multi-tenant deployment (REQUIRE_PRINCIPAL). Gates the full-body `WebFetch` tool out of the
      *  default roster — core says a multi-tenant deployment MUST allowlist hosts (an injected/malicious tenant model
      *  could exfil via an arbitrary public URL; the SSRF floor only blocks internal). Single-user TOC keeps WebFetch. */

package/dist/capabilities/scenarios.js

@@ -1,7 +1,7 @@
 import { CODE_AGENT_PROMPT, CODE_SYSTEM_PROMPT, DEFAULT_SYSTEM_PROMPT, assembleCodeTools, defaultTaskRegistry } from "@sema-agent/core";
 import { HttpError } from "../security.js";
 import { nowTool } from "./builtin-tools.js";
-import { GiteaClient, parseRepo, repoToolsFor } from "./repo-tools.js";
+import { parseRepo, repoToolsFor } from "./repo-tools.js";
 import { createCouncilTool, clampRounds } from "./code-review-council.js";
 import { stablePrompt } from "./prompt.js";
 import { createTeamTool, teamCoordinatorPrompt, getTeam, teamNames } from "./team.js";
@@ -407,6 +407,12 @@ function codeReview(deps, req) {
     // #196:两条腿(直评 / council)都声明 none —— 直评腿的 lead 只读仓库工具,council 腿的 lead 只调
     // run_council;lens/arbiter 子任务同样只读仓库,故 council 工具拿无手 subRunner。
     const hands = "none";
+    // [C143]:lenses 非 number 形响亮拒——此前 string[]/任意形静默滑过(typeof 门恒 false 整键落空),
+    // client-core 0.22.0 曾按想象契约钉 string[],用户发出的键被静默吞([C142] web-client wire 实证)。
+    // 与 (a) 案(client-core 改 number)对齐后客户端不会再发该形;本 400 是防第三方直调的纵深。
+    if (req.lenses !== undefined && typeof req.lenses !== "number") {
+        throw new HttpError(400, "lenses must be a number (council lens COUNT, 1-6) — a named lens subset is not a request-level knob", { code: "request.field_invalid" });
+    }
     if (req.council === true) {
         const rounds = clampRounds(req.rounds); // finite-guarded (NaN/±Inf → undefined → council default 1)
         return {
@@ -427,7 +433,10 @@ function codeReview(deps, req) {
             promptProvider: coordinatorPrompt,
         };
     }
-    return { tools: repoTools, hands, skills, promptProvider: directReviewerPrompt };
+    // [C144]([3296]⑤ web-client 实证):直评腿补 nowTool 与 scan 对齐——此前真装配无 Now 而 capabilities
+    // 声明 fallback 表 REPO_TOOLS 含 Now(repoClient 缺席时 probe 落 fallback 多报一枚=声明/装配错位;
+    // scan 当年照本场景抄还多加了 Now)。对齐后 fallback 表自动变准,评审报告带时间戳同样合理。
+    return { tools: [...repoTools, nowTool()], hands, skills, promptProvider: directReviewerPrompt };
 }
 const reviewBody = "Produce ONE prioritized review: a short summary, then findings grouped by severity " +
     "(blocker / major / minor), each with `path:line`, the problem, and a concrete fix. Cite real code — never invent files or symbols.";

package/dist/config-types.d.ts

@@ -12,6 +12,7 @@ import type { ElicitationThrottle } from "./elicitation.js";
 import type { QuestionThrottle } from "./question.js";
 import type { InfraCostRates } from "./observability/cost-taxonomy.js";
 import type { Autonomy, CommandRule } from "./runtime-governance.js";
+import type { GitApiKind } from "./git-api-kind.js";
 /** A sema-registry MCP server resolved to a core spec (env-NAME refs already → real values) plus the
  *  scenarios it applies to (empty = all). `resolveSpec` filters by scenario and passes `spec` to core. */
 export interface ScopedMcpServer {
@@ -634,11 +635,15 @@ export interface ServiceConfigFlat {
      *  OFF (in-process, faster). `SELF_ORCHESTRATION_WORKER_ISOLATION=true`. */
     selfOrchestrationWorkerIsolation: boolean;
     /** SVC-1: the durable WorkflowRunStore backend for BACKGROUND workflow runs.
-     *  `file` (DEFAULT) = the crash-safe `FileWorkflowRunStore` ledger under `localDataRoot/workflows` — a
-     *  background run's record SURVIVES a restart, which is what lets the at-least-once completion notify re-derive
-     *  a run's terminal state after a crash. `memory` = the ephemeral `InMemoryWorkflowRunStore` (process-local; no
-     *  crash recovery, no notify journal) — an explicit opt-out for a single-instance/ephemeral deployment.
-     *  `WORKFLOW_RUN_STORE=file|memory`. Only consulted when SELF_ORCHESTRATION_ENABLED. */
+     *  `auto` (DEFAULT) = the SQL-backed cross-replica store when a SQL backend is configured, else the
+     *  crash-safe `FileWorkflowRunStore` ledger under `localDataRoot/workflows` (dispatch: main.ts, keyed off
+     *  `sqlWorkflowRunStore` presence). `file` = force the file ledger even with SQL present (single-replica
+     *  pinning). Either durable form means a background run's record SURVIVES a restart, which is what lets the
+     *  at-least-once completion notify re-derive a run's terminal state after a crash. `memory` = the ephemeral
+     *  `InMemoryWorkflowRunStore` (process-local; no crash recovery, no notify journal) — an explicit opt-out for
+     *  a single-instance/ephemeral deployment. (A-002.18: the old docblock claimed `file` was the default and
+     *  omitted `auto` entirely — a reader picking a backend off this comment would never learn the SQL twin
+     *  exists.) `WORKFLOW_RUN_STORE=auto|file|memory`. Only consulted when SELF_ORCHESTRATION_ENABLED. */
     workflowRunStoreBackend: "auto" | "file" | "memory";
     /** SVC-1 (adversarial-review): a workflow still `running` past this age is deemed a crash-orphan by the periodic
      *  notify-recovery sweep (core never resumes/reaps a prior `running` row) → finalized-as-abandoned so the
@@ -962,6 +967,10 @@ export interface ServiceConfigFlat {
     gitApiBaseUrl?: string;
     /** Read-only Git host token (server-side only; never reaches the model). */
     gitApiToken?: string;
+    /** Git host API dialect for the repo tools (env GIT_API_KIND, closed set gitea|github; default gitea).
+     *  "github" = api.github.com or GHE `/api/v3` root — the Gitea client's `/api/v1` + `.diff` shapes
+     *  404 there (P1-2: our own repos live on GitHub and were unreviewable). Unknown word = refuse boot. */
+    gitApiKind: GitApiKind;
     /** S3-TOB 设计 §1.3:memory 持久面方言(env MEMORY_ENGINE_BACKEND,缺省 file)。boot-only。 */
     memoryEngineBackend: "file" | "pg" | "tidb";
     /** CC `workflowSizeGuideline` (advisory, injected into the Workflow tool card via
@@ -1013,7 +1022,7 @@ export type ServiceLimitsHttpConfig = Pick<ServiceConfigFlat, "port" | "attachme
 /** 组:observability(可观测)。 */
 export type ServiceObservabilityConfig = Pick<ServiceConfigFlat, "metricsToken" | "traceToken" | "toolTrace" | "traceThinking" | "logLevel" | "otel">;
 /** 组:integrations(外部集成)。`mcpServers` 由 sema-registry 适配器填(无 env 腿),归本组。 */
-export type ServiceIntegrationsConfig = Pick<ServiceConfigFlat, "pluginsAllowHosts" | "mcpServers" | "configBootFetchBudgetMs" | "gitApiBaseUrl" | "gitApiToken" | "defaultScenario" | "skillsDir" | "configCenter" | "configProvider" | "configLocalDir">;
+export type ServiceIntegrationsConfig = Pick<ServiceConfigFlat, "pluginsAllowHosts" | "mcpServers" | "configBootFetchBudgetMs" | "gitApiBaseUrl" | "gitApiToken" | "gitApiKind" | "defaultScenario" | "skillsDir" | "configCenter" | "configProvider" | "configLocalDir">;
 /** 九个组槽。每组恒在场(`loadConfig` / `attachConfigGroups` 装好才交出配置),故不可选——新代码写
  *  `config.modelPlane.model` 不需要 `?.`(可选组会把 `Model` 污染成 `Model | undefined`)。 */
 export interface ServiceConfigGroups {

package/dist/config.js

@@ -5,7 +5,9 @@ import { CODE_AGENT_PROMPT, formatUserScope, isThinkingLevel, PROTOCOL_TABLE, pr
 import { ROSTER_PRIMARY_ROLES, ROSTER_CHEAP_ROLES } from "@sema-agent/registry-core";
 import { parseApprovalHmacKeys, parsePrincipalJwks } from "./auth-keys.js"; // design/158 A4: the parser leaf — NOT security.js (base config layer must not value-import the 55KiB auth module)
 import { DEFAULT_ELICITATION_THROTTLE } from "./elicitation.js";
+import { isV2ScopeKey } from "./memory-scope.js"; // A-002.4: v2 scope 前缀词表的单一属主(纯谓词,无反向依赖)
 import { DEFAULT_QUESTION_THROTTLE } from "./question.js";
+import { GIT_API_KINDS, isGitApiKind } from "./git-api-kind.js"; // P1-2: 方言词表叶模块(config 不得值引 capabilities 层)
 function csv(name) {
     return (process.env[name] ?? "")
         .split(",")
@@ -1109,7 +1111,9 @@ function parseMemoryDomain(ctx) {
         if (memorySyncToken === undefined) {
             throw new Error("MEMORY_SYNC_URL is set but MEMORY_SYNC_TOKEN is not — refusing to start half-configured (the central sync face requires a bearer token)");
         }
-        const isV2ScopeKey = (k) => k.startsWith("user:") || k.startsWith("org:") || k.startsWith("proj:") || k.startsWith("userproj:");
+        // A-002.4:前缀判据的**唯一属主**是 memory-scope.ts(此处曾有一份逐字副本;两处咬合用途不同,
+        // 但 core 加第五种 typed 前缀时必须一起动,否则同一个键在「挂 v2 标」和「算不算已是 v2 键」两处
+        // 得出相反答案 ⇒ 这里会把它再包成 `user:user%3A…` 双包键)。
         const scope = memorySyncScopeRaw ?? (memoryScope !== undefined ? (isV2ScopeKey(memoryScope) ? memoryScope : formatUserScope(memoryScope)) : undefined);
         if (scope === undefined) {
             throw new Error("MEMORY_SYNC_URL is set but no sync scope is derivable (memory engine off or multi-tenant without an explicit scope) — set MEMORY_SYNC_SCOPE, or run the single-user file memory engine so MEMORY_SCOPE (default \"local\") provides one");
@@ -1498,6 +1502,42 @@ function parseObservabilityDomain() {
             : undefined,
     };
 }
+/** GIT_API_KIND:repo 工具的 Git-host 方言(闭集 gitea|github,缺省 gitea)。
+ *  未知词=拒启(安全轴词表纪律);另一坏形也拒启:kind 缺省/gitea 而 BASEURL 指向 github.com——
+ *  Gitea 形状(`/api/v1` 前缀、`.diff` 后缀)对 GitHub 恒 404,与其在任务运行时逐调用 loud 404,
+ *  不如启动即指路(#123 FLEET_ADVERTISE_ADDRESS 坏形响亮拒同族)。 */
+function parseGitApiKind(raw, baseUrl) {
+    const kind = raw ?? "gitea";
+    if (!isGitApiKind(kind)) {
+        throw new Error(`GIT_API_KIND="${raw}" is not a known Git host kind (expected one of: ${GIT_API_KINDS.join(", ")})`);
+    }
+    if (!baseUrl)
+        return kind;
+    // 配了就必须是合法 URL(USAGE 本就要求带 scheme 的完整 baseURL;坏 URL 此前静默过门、逐调用 fetch
+    // 才炸 —— 启动即拒;codex F3)。尾点主机(api.github.com.)DNS 等价,归一后再比对,防绕过。
+    if (!URL.canParse(baseUrl)) {
+        throw new Error(`GIT_API_BASEURL="${baseUrl}" is not a valid URL (expected e.g. https://git.example.com)`);
+    }
+    const u = new URL(baseUrl);
+    const host = u.hostname.replace(/\.$/, "").toLowerCase();
+    const githubFamily = host === "github.com" || host === "api.github.com" || host.endsWith(".github.com");
+    if (kind === "gitea" && githubFamily) {
+        throw new Error(`GIT_API_BASEURL points at ${host} but GIT_API_KIND is "gitea" — the Gitea API shapes 404 on GitHub. Set GIT_API_KIND=github (base url should be https://api.github.com, or your GHE /api/v3 root).`);
+    }
+    if (kind === "github") {
+        // 对称校验(codex F3):web 域名/带 path 的 api 根都会让每个仓操作 404,而客户端照建、场景照宣可用。
+        if (githubFamily && host !== "api.github.com") {
+            throw new Error(`GIT_API_BASEURL host ${host} is the GitHub WEB host — the API root is https://api.github.com (a repo page URL is not an API base).`);
+        }
+        if (host === "api.github.com" && u.pathname !== "/" && u.pathname !== "") {
+            throw new Error(`GIT_API_BASEURL for github.com must be exactly https://api.github.com (no path; got path "${u.pathname}"). GHE uses https://<ghe-host>/api/v3.`);
+        }
+        if (u.search || u.hash) {
+            throw new Error(`GIT_API_BASEURL must not carry a query or fragment (got "${baseUrl}")`);
+        }
+    }
+    return kind;
+}
 /** 域:misc-integration(外部集成)—— plugins clone 白名单、git/OA 面、场景与 skill 目录、sema-registry 接入。 */
 function parseIntegrationsDomain() {
     return {
@@ -1506,6 +1546,7 @@ function parseIntegrationsDomain() {
         configBootFetchBudgetMs: Math.max(0, numEnv("CONFIG_BOOT_FETCH_BUDGET_MS", "1500")), // boot 首拉抢答窗;过窗转后台补齐(clay 2026-07-17:本地 5s 启动=黑洞中心同步等待)
         gitApiBaseUrl: process.env.GIT_API_BASEURL,
         gitApiToken: process.env.GIT_API_TOKEN,
+        gitApiKind: parseGitApiKind(process.env.GIT_API_KIND, process.env.GIT_API_BASEURL),
         // BEHAVIOR CHANGE([891] clay 硬裁定):出厂缺省场景 default→code(CC 编码 persona 蒸馏版)——
         // 编码产品出厂态对标 CC 出厂态,通用域中性 persona 用 DEFAULT_SCENARIO=default 显式选回。
         defaultScenario: env("DEFAULT_SCENARIO", "code"),
@@ -1567,7 +1608,7 @@ const LIMITS_HTTP_GROUP_KEYS = [
 ];
 const OBSERVABILITY_GROUP_KEYS = ["metricsToken", "traceToken", "toolTrace", "traceThinking", "logLevel", "otel"];
 const INTEGRATIONS_GROUP_KEYS = [
-    "pluginsAllowHosts", "mcpServers", "configBootFetchBudgetMs", "gitApiBaseUrl", "gitApiToken", "defaultScenario",
+    "pluginsAllowHosts", "mcpServers", "configBootFetchBudgetMs", "gitApiBaseUrl", "gitApiToken", "gitApiKind", "defaultScenario",
     "skillsDir", "configCenter", "configProvider", "configLocalDir",
 ];
 /** 组名 → 该组取景的平铺键(introspection 面:测试用它钉「每个平铺键恰好被一组取景」)。 */

package/dist/fleet/fleet-terminal-window.d.ts

@@ -43,7 +43,7 @@ export declare const FLEET_SNAPSHOT_TERMINAL_MAX_ROWS = 20;
  * 每个终态**扫描面**的行数(店侧下推的 limit)。它比 {@link FLEET_SNAPSHOT_TERMINAL_MAX_ROWS} 大是有
  * 具体病灶的(codex R1-M3,红先复现):店侧分页按 `createdAt DESC` 排(core 契约 + 两个 SQL 实现皆然),
  * 而本窗的判据是**结束时刻**——一条跑了三天、刚刚才结束的 workflow(正是用户此刻要看的那条)会被 20 条
- * 更晚创建的行挤出首页。留这段余量是在现有契约内能给的最好答案;彻底解法是店侧加一个 `ended_at DESC`
+ * 更晚创建的行挤出首页。留这段余量是在现有契约内能给的最好答案;彻底解法是店侧加一个 `ended_at_ms DESC`
  * 的窄查询(要过真双库门,已作移交项记在发车说明里)。
  *
  * 残余(如实记档):同 scope 同一终态下,若有超过本值条**更晚创建**的行,那条"早创建、刚结束"的行仍会

package/dist/fleet/fleet-terminal-window.js

@@ -44,7 +44,7 @@ export const FLEET_SNAPSHOT_TERMINAL_MAX_ROWS = 20;
  * 每个终态**扫描面**的行数(店侧下推的 limit)。它比 {@link FLEET_SNAPSHOT_TERMINAL_MAX_ROWS} 大是有
  * 具体病灶的(codex R1-M3,红先复现):店侧分页按 `createdAt DESC` 排(core 契约 + 两个 SQL 实现皆然),
  * 而本窗的判据是**结束时刻**——一条跑了三天、刚刚才结束的 workflow(正是用户此刻要看的那条)会被 20 条
- * 更晚创建的行挤出首页。留这段余量是在现有契约内能给的最好答案;彻底解法是店侧加一个 `ended_at DESC`
+ * 更晚创建的行挤出首页。留这段余量是在现有契约内能给的最好答案;彻底解法是店侧加一个 `ended_at_ms DESC`
  * 的窄查询(要过真双库门,已作移交项记在发车说明里)。
  *
  * 残余(如实记档):同 scope 同一终态下,若有超过本值条**更晚创建**的行,那条"早创建、刚结束"的行仍会

package/dist/git-api-kind.d.ts

@@ -0,0 +1,7 @@
+/** Git-host API dialect word table (P1-2). Leaf module — the single owner shared by the config layer
+ *  (env parse/validation) and `capabilities/repo-tools` (the two client implementations); config must not
+ *  value-import the capabilities layer (module-cycle gate §G), so the table lives below both. */
+export declare const GIT_API_KINDS: readonly ["gitea", "github"];
+export type GitApiKind = (typeof GIT_API_KINDS)[number];
+export declare function isGitApiKind(v: unknown): v is GitApiKind;
+//# sourceMappingURL=git-api-kind.d.ts.map

package/dist/git-api-kind.js

@@ -0,0 +1,8 @@
+/** Git-host API dialect word table (P1-2). Leaf module — the single owner shared by the config layer
+ *  (env parse/validation) and `capabilities/repo-tools` (the two client implementations); config must not
+ *  value-import the capabilities layer (module-cycle gate §G), so the table lives below both. */
+export const GIT_API_KINDS = ["gitea", "github"];
+export function isGitApiKind(v) {
+    return typeof v === "string" && GIT_API_KINDS.includes(v);
+}
+//# sourceMappingURL=git-api-kind.js.map