@sema-agent/server 7.9.0 → 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

@@ -84,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/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";

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 {
@@ -966,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
@@ -1017,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

@@ -7,6 +7,7 @@ import { parseApprovalHmacKeys, parsePrincipalJwks } from "./auth-keys.js"; // d
 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(",")
@@ -1501,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 {
@@ -1509,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"),
@@ -1570,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

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 投影的老行)

package/dist/http/server.js

@@ -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/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)` 这组条件下的行数天然极小,
      * 一次全量返回,结构上没有分页假阴性。
      *
      * 三条口径,逐条都是判据:

package/dist/plugins/checkpoint-store-sql.js

@@ -37,7 +37,7 @@ import { mysqlDriver, pgDriver, dialectProtocolJsonEncoder } from "./sql-driver.
 const MAX_TOOL_INPUT_CHARS = 8192;
 /**
  * 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).
@@ -46,15 +46,15 @@ const MAX_TOOL_INPUT_CHARS = 8192;
  */
 export const TERMINAL_BACKSTOP_MS = Math.max(60_000, Number(process.env.APPROVAL_TERMINAL_BACKSTOP_MS) || 30 * 86_400_000);
 /**
- * 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
  * it never meaningfully delays the eventual crash-safe GC.
  */
-export const TERMINAL_GRACE_MS = 3_600_000; // exported for the LOCAL twin's read-time terminal_at derivation (anti-drift) // 1h — many reaper intervals of deny-sweep runway past the SLA deadline
+export const TERMINAL_GRACE_MS = 3_600_000; // exported for the LOCAL twin's read-time terminal_at_ms derivation (anti-drift) // 1h — many reaper intervals of deny-sweep runway past the SLA deadline
 /**
  * The capability token IS the resume credential (token-as-auth) — anyone who reads it can impersonate a
  * resume, so it must never reach the logs (which fan out to a log-aggregation pipeline). For the diagnostic
@@ -303,8 +303,8 @@ export class SqlCheckpointStore {
         // payload without an N+1 trace.turns fetch. Stored as a stringified JSON column value.
         const toolInput = boundedToolInput(pa?.args);
         try {
-            await this.db.query(this.q("INSERT INTO checkpoint (token, scope, session_id, version, status, tool_name, tool_call_id, tool_input, checkpoint, deadline, created_at, terminal_at, gate_kind, bound_input_hash, risk_descriptor) " +
-                "VALUES (?,?,?,?,'pending',?,?,?,?,?,?,?,?,?,?)", "INSERT INTO checkpoint (token, scope, session_id, version, status, tool_name, tool_call_id, tool_input, checkpoint, deadline, created_at, terminal_at, gate_kind, bound_input_hash, risk_descriptor) " +
+            await this.db.query(this.q("INSERT INTO checkpoint (token, scope, session_id, version, status, tool_name, tool_call_id, tool_input, checkpoint, deadline, created_at_ms, terminal_at_ms, gate_kind, bound_input_hash, risk_descriptor) " +
+                "VALUES (?,?,?,?,'pending',?,?,?,?,?,?,?,?,?,?)", "INSERT INTO checkpoint (token, scope, session_id, version, status, tool_name, tool_call_id, tool_input, checkpoint, deadline, created_at_ms, terminal_at_ms, gate_kind, bound_input_hash, risk_descriptor) " +
                 "VALUES ($1,$2,$3,$4,'pending',$5,$6,$7::jsonb,$8::jsonb,$9,$10,$11,$12,$13,$14)"), [
                 token,
                 cp.scope,
@@ -316,7 +316,7 @@ export class SqlCheckpointStore {
                 this.json(cp, "checkpoint"),
                 cp.deadline ?? null,
                 cp.createdAt,
-                Math.max(cp.createdAt + TERMINAL_BACKSTOP_MS, (cp.deadline ?? 0) + TERMINAL_GRACE_MS), // D-1 §3 inv#3 backstop — STRICTLY after any SLA deadline (grace) so the terminal_at-branch never races the D-D deny-sweep, and never pre-empts an operator's longer TTL
+                Math.max(cp.createdAt + TERMINAL_BACKSTOP_MS, (cp.deadline ?? 0) + TERMINAL_GRACE_MS), // D-1 §3 inv#3 backstop — STRICTLY after any SLA deadline (grace) so the terminal_at_ms-branch never races the D-D deny-sweep, and never pre-empts an operator's longer TTL
                 cp.gate?.kind ?? null, // D-D SLA split: human/irreversible_ask deadline → resolve-deny; others → expire
                 pa?.boundInputHash ?? null, // D-1: the opaque hash the portal must echo on /decide (surfaced via listPending so the TOCTOU binding is reachable)
                 ((g) => (g?.riskDescriptor ? this.json(g.riskDescriptor, "risk descriptor") : null))(cp.gate), // riskDescriptor inbox: stamp core's INERT descriptor for triage-sort
@@ -413,8 +413,8 @@ export class SqlCheckpointStore {
         const params = [this.json(outcome, "checkpoint outcome"), Date.now(), token, scope];
         if (expect)
             params.push(expect.rev);
-        const res = await this.db.query(this.q("UPDATE checkpoint SET status = 'resolved', outcome = ?, decided_at = ?, rev = rev + 1, reopen_reason = NULL WHERE token = ? AND scope = ? AND status = 'pending'" +
-            (expect ? " AND rev = ?" : ""), "UPDATE checkpoint SET status = 'resolved', outcome = $1::jsonb, decided_at = $2, rev = rev + 1, reopen_reason = NULL WHERE token = $3 AND scope = $4 AND status = 'pending'" +
+        const res = await this.db.query(this.q("UPDATE checkpoint SET status = 'resolved', outcome = ?, decided_at_ms = ?, rev = rev + 1, reopen_reason = NULL WHERE token = ? AND scope = ? AND status = 'pending'" +
+            (expect ? " AND rev = ?" : ""), "UPDATE checkpoint SET status = 'resolved', outcome = $1::jsonb, decided_at_ms = $2, rev = rev + 1, reopen_reason = NULL WHERE token = $3 AND scope = $4 AND status = 'pending'" +
             (expect ? " AND rev = $5" : "")), params);
         return res.affected === 1;
     }
@@ -508,19 +508,19 @@ export class SqlCheckpointStore {
      * Uses `expired` (not a `resolve`-deny) so a CANCELLED checkpoint never pollutes resolved-count / outcome.
      */
     async expire(token, scope) {
-        const res = await this.db.query(this.q("UPDATE checkpoint SET status = 'expired', decided_at = ? WHERE token = ? AND scope = ? AND status = 'pending'", "UPDATE checkpoint SET status = 'expired', decided_at = $1 WHERE token = $2 AND scope = $3 AND status = 'pending'"), [Date.now(), token, scope]);
+        const res = await this.db.query(this.q("UPDATE checkpoint SET status = 'expired', decided_at_ms = ? WHERE token = ? AND scope = ? AND status = 'pending'", "UPDATE checkpoint SET status = 'expired', decided_at_ms = $1 WHERE token = $2 AND scope = $3 AND status = 'pending'"), [Date.now(), token, scope]);
         return res.affected === 1;
     }
     /** Interface reap: CAS-expire pending checkpoints in `scope` past `cutoff`. Returns count. */
     async reap(scope, cutoff) {
-        const res = await this.db.query(this.q("UPDATE checkpoint SET status = 'expired', decided_at = ? WHERE scope = ? AND status = 'pending' AND deadline IS NOT NULL AND deadline <= ?", "UPDATE checkpoint SET status = 'expired', decided_at = $1 WHERE scope = $2 AND status = 'pending' AND deadline IS NOT NULL AND deadline <= $3"), [Date.now(), scope, cutoff]);
+        const res = await this.db.query(this.q("UPDATE checkpoint SET status = 'expired', decided_at_ms = ? WHERE scope = ? AND status = 'pending' AND deadline IS NOT NULL AND deadline <= ?", "UPDATE checkpoint SET status = 'expired', decided_at_ms = $1 WHERE scope = $2 AND status = 'pending' AND deadline IS NOT NULL AND deadline <= $3"), [Date.now(), scope, cutoff]);
         return res.affected;
     }
     /**
      * 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
@@ -529,14 +529,14 @@ export class SqlCheckpointStore {
      * 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).
      */
     async reapExpired(cutoff) {
-        const res = await this.db.query(this.q("UPDATE checkpoint SET status = 'expired', decided_at = ? " +
-            `WHERE status = 'pending' AND ((deadline IS NOT NULL AND deadline <= ? AND (gate_kind IS NULL OR gate_kind NOT IN ${APPROVAL_GATE_KINDS_SQL_IN} OR COALESCE(tool_name,'') = 'AskUserQuestion')) OR (terminal_at IS NOT NULL AND terminal_at <= ?))`, "UPDATE checkpoint SET status = 'expired', decided_at = $1 " +
-            `WHERE status = 'pending' AND ((deadline IS NOT NULL AND deadline <= $2 AND (gate_kind IS NULL OR gate_kind NOT IN ${APPROVAL_GATE_KINDS_SQL_IN} OR COALESCE(tool_name,'') = 'AskUserQuestion')) OR (terminal_at IS NOT NULL AND terminal_at <= $3))`), [Date.now(), cutoff, cutoff]);
+        const res = await this.db.query(this.q("UPDATE checkpoint SET status = 'expired', decided_at_ms = ? " +
+            `WHERE status = 'pending' AND ((deadline IS NOT NULL AND deadline <= ? AND (gate_kind IS NULL OR gate_kind NOT IN ${APPROVAL_GATE_KINDS_SQL_IN} OR COALESCE(tool_name,'') = 'AskUserQuestion')) OR (terminal_at_ms IS NOT NULL AND terminal_at_ms <= ?))`, "UPDATE checkpoint SET status = 'expired', decided_at_ms = $1 " +
+            `WHERE status = 'pending' AND ((deadline IS NOT NULL AND deadline <= $2 AND (gate_kind IS NULL OR gate_kind NOT IN ${APPROVAL_GATE_KINDS_SQL_IN} OR COALESCE(tool_name,'') = 'AskUserQuestion')) OR (terminal_at_ms IS NOT NULL AND terminal_at_ms <= $3))`), [Date.now(), cutoff, cutoff]);
         return res.affected;
     }
     /**
@@ -560,11 +560,11 @@ export class SqlCheckpointStore {
      *  joined from task_active (the JOIN KEY to the run/trace — a suspended run KEEPS its
      *  session claim, so the join is live for every pending row; null only in pathological windows). */
     async listPending(scope) {
-        const base = "SELECT c.session_id, c.scope, c.tool_name, c.tool_call_id, c.tool_input, c.bound_input_hash, c.risk_descriptor, c.created_at, c.deadline, c.gate_kind, ta.task_id " +
+        const base = "SELECT c.session_id, c.scope, c.tool_name, c.tool_call_id, c.tool_input, c.bound_input_hash, c.risk_descriptor, c.created_at_ms, c.deadline, c.gate_kind, ta.task_id " +
             "FROM checkpoint c LEFT JOIN task_active ta ON ta.session_id = c.session_id WHERE c.status='pending'";
         const { rows } = scope
-            ? await this.db.query(`${base}${this.q(" AND c.scope=?", " AND c.scope=$1")} ORDER BY c.created_at ASC`, [scope])
-            : await this.db.query(`${base} ORDER BY c.created_at ASC`);
+            ? await this.db.query(`${base}${this.q(" AND c.scope=?", " AND c.scope=$1")} ORDER BY c.created_at_ms ASC`, [scope])
+            : await this.db.query(`${base} ORDER BY c.created_at_ms ASC`);
         const out = rows.map((r) => {
             const toolCallId = r.tool_call_id ?? null;
             const boundInputHash = r.bound_input_hash ?? null;
@@ -587,7 +587,7 @@ export class SqlCheckpointStore {
                 // Both drivers return the JSON column already parsed; null for pre-migration rows. PG 库内恒干净
                 // (拒绝式)——直读即审阅面=执行面。
                 input: r.tool_input ?? null,
-                createdAt: Number(r.created_at),
+                createdAt: Number(r.created_at_ms),
                 deadline: r.deadline == null ? null : Number(r.deadline),
                 riskDescriptor: parseJson(r.risk_descriptor),
             };
@@ -602,14 +602,14 @@ export class SqlCheckpointStore {
      * (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
      * ceiling that still protects memory/latency if a scope ever accumulates pathologically many pending gates.
      */
     async listByScope(scope) {
-        const { rows } = await this.db.query(this.q("SELECT checkpoint, status FROM checkpoint WHERE status = 'pending' AND scope = ? ORDER BY created_at ASC LIMIT 500", "SELECT checkpoint, status FROM checkpoint WHERE status = 'pending' AND scope = $1 ORDER BY created_at ASC LIMIT 500"), [scope]);
+        const { rows } = await this.db.query(this.q("SELECT checkpoint, status FROM checkpoint WHERE status = 'pending' AND scope = ? ORDER BY created_at_ms ASC LIMIT 500", "SELECT checkpoint, status FROM checkpoint WHERE status = 'pending' AND scope = $1 ORDER BY created_at_ms ASC LIMIT 500"), [scope]);
         const out = [];
         for (const r of rows) {
             // A corrupt/missing blob skips THAT row rather than crashing the whole scheduler view (review w16yqkkxv):
@@ -638,7 +638,7 @@ export class SqlCheckpointStore {
      *
      * 「这条 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)` 这组条件下的行数天然极小,
      * 一次全量返回,结构上没有分页假阴性。
      *
      * 三条口径,逐条都是判据:
@@ -661,9 +661,9 @@ export class SqlCheckpointStore {
      * 维,列命中行结构上也必须解 blob 才拿得到它。
      */
     async findCheckpointCandidatesForAsk(scope, sessionId, toolCallId, sinceMs) {
-        const { rows } = await this.db.query(this.q("SELECT token, status, created_at, tool_call_id, bound_input_hash, version, checkpoint FROM checkpoint " +
-            "WHERE scope=? AND session_id=? AND created_at>=? AND (tool_call_id=? OR tool_call_id IS NULL) ORDER BY created_at ASC", "SELECT token, status, created_at, tool_call_id, bound_input_hash, version, checkpoint FROM checkpoint " +
-            "WHERE scope=$1 AND session_id=$2 AND created_at>=$3 AND (tool_call_id=$4 OR tool_call_id IS NULL) ORDER BY created_at ASC"), [scope, sessionId, sinceMs, toolCallId]);
+        const { rows } = await this.db.query(this.q("SELECT token, status, created_at_ms, tool_call_id, bound_input_hash, version, checkpoint FROM checkpoint " +
+            "WHERE scope=? AND session_id=? AND created_at_ms>=? AND (tool_call_id=? OR tool_call_id IS NULL) ORDER BY created_at_ms ASC", "SELECT token, status, created_at_ms, tool_call_id, bound_input_hash, version, checkpoint FROM checkpoint " +
+            "WHERE scope=$1 AND session_id=$2 AND created_at_ms>=$3 AND (tool_call_id=$4 OR tool_call_id IS NULL) ORDER BY created_at_ms ASC"), [scope, sessionId, sinceMs, toolCallId]);
         const out = [];
         for (const r of rows) {
             // `sourceTaskId: null` 是**所有 unparseable 臂的共同底**(读不出的行不许带出一个可用于身份比对的
@@ -671,7 +671,7 @@ export class SqlCheckpointStore {
             const base = {
                 token: String(r.token),
                 status: String(r.status),
-                createdAtMs: Number(r.created_at),
+                createdAtMs: Number(r.created_at_ms),
                 boundInputHash: r.bound_input_hash == null ? null : String(r.bound_input_hash),
                 sourceTaskId: null,
             };

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

@@ -84,7 +84,7 @@ export declare class LocalCheckpointStore {
      * design/80 D-D global expiry sweep — same kind-split as the TiDB twin: the deadline branch abort-expires
      * every kind EXCEPT a human/irreversible_ask approval gate (those get the graceful resolve-DENY via
      * listExpiredApprovalGates), with the AskUserQuestion carve-back (denying a question is incoherent → expire);
-     * the terminal_at branch (derived read-time via the SAME formula the TiDB put stamps) abort-expires ANY kind.
+     * the terminal_at_ms branch (derived read-time via the SAME formula the TiDB put stamps) abort-expires ANY kind.
      */
     reapExpired(cutoff: number): Promise<number>;
     /** design/80 D-D SLA deny-sweep input — pending human/irreversible_ask gates past deadline (excl. AskUserQuestion). */

package/dist/plugins/local-checkpoint-store.js

@@ -26,7 +26,7 @@ import { join } from "node:path";
 import { isApprovalGateKind } from "../tool-approval.js"; // A-002.1 单一属主
 import { FileCheckpointStore, atomicWriteFile, sanitizePathComponent, } from "@sema-agent/core";
 import { boundedToolInput, TERMINAL_BACKSTOP_MS, TERMINAL_GRACE_MS } from "./checkpoint-store-sql.js";
-/** design/80 D-D read-time twin of the TiDB put-time `terminal_at` column (same formula — anti-drift). */
+/** design/80 D-D read-time twin of the TiDB put-time `terminal_at_ms` column (same formula — anti-drift). */
 function terminalAtOf(cp) {
     return Math.max(cp.createdAt + TERMINAL_BACKSTOP_MS, (cp.deadline ?? 0) + TERMINAL_GRACE_MS);
 }
@@ -286,7 +286,7 @@ export class LocalCheckpointStore {
      * design/80 D-D global expiry sweep — same kind-split as the TiDB twin: the deadline branch abort-expires
      * every kind EXCEPT a human/irreversible_ask approval gate (those get the graceful resolve-DENY via
      * listExpiredApprovalGates), with the AskUserQuestion carve-back (denying a question is incoherent → expire);
-     * the terminal_at branch (derived read-time via the SAME formula the TiDB put stamps) abort-expires ANY kind.
+     * the terminal_at_ms branch (derived read-time via the SAME formula the TiDB put stamps) abort-expires ANY kind.
      */
     async reapExpired(cutoff) {
         let n = 0;

package/dist/plugins/memory-engine-pg.js

@@ -44,8 +44,8 @@ export async function ensurePgMemoryEngineSchema(query, opts = {}) {
     const embeddingCol = vec?.pgvector ? `vector(${vec.dimensions})` : "jsonb";
     await query(`CREATE TABLE IF NOT EXISTS ${PG_MEMORY_ENGINE_TABLES.entry} (
     id text COLLATE "C" PRIMARY KEY,
-    scope text COLLATE "C" NOT NULL,
-    slug text COLLATE "C" NOT NULL,
+    scope varchar(190) COLLATE "C" NOT NULL,
+    slug varchar(512) COLLATE "C" NOT NULL,
     frontmatter jsonb NOT NULL,
     body text COLLATE "C" NOT NULL,
     rev text COLLATE "C" NOT NULL,
@@ -66,7 +66,7 @@ export async function ensurePgMemoryEngineSchema(query, opts = {}) {
     // suffix. NOT wrapped in try/catch — if this constraint cannot be created, the backend is unsafe.
     await query(`CREATE UNIQUE INDEX IF NOT EXISTS uq_${PG_MEMORY_ENGINE_TABLES.entry}_scope_slug ON ${PG_MEMORY_ENGINE_TABLES.entry} (scope, slug)`);
     await query(`CREATE TABLE IF NOT EXISTS ${PG_MEMORY_ENGINE_TABLES.cursor} (
-    scope text COLLATE "C" PRIMARY KEY,
+    scope varchar(190) COLLATE "C" PRIMARY KEY,
     cursor text COLLATE "C" NOT NULL
   )`);
 }

package/dist/plugins/pg-pool.js

@@ -96,11 +96,11 @@ export const PG_SCHEMA_STATEMENTS = [
      checkpoint   JSONB        NOT NULL,
      outcome      JSONB,
      deadline     BIGINT,
-     created_at   BIGINT       NOT NULL,
-     decided_at   BIGINT,
+     created_at_ms BIGINT      NOT NULL,
+     decided_at_ms BIGINT,
      rev          BIGINT       NOT NULL DEFAULT 0,
      reopen_reason VARCHAR(32) COLLATE "C",
-     terminal_at  BIGINT,
+     terminal_at_ms BIGINT,
      gate_kind    VARCHAR(32) COLLATE "C",
      bound_input_hash VARCHAR(190) COLLATE "C",
      -- pending_steer / pending_steer_queue / pending_steer_rev:队列化后的 durable steering(core 5.14.0
@@ -222,7 +222,7 @@ export const PG_SCHEMA_STATEMENTS = [
      source_run_id VARCHAR(191) COLLATE "C" NOT NULL,
      scope         VARCHAR(190) COLLATE "C" NOT NULL,
      new_run_id    VARCHAR(191) COLLATE "C" NOT NULL,
-     claimed_at    BIGINT       NOT NULL,
+     claimed_at_ms BIGINT       NOT NULL,
      PRIMARY KEY (source_run_id, scope)
    )`,
     // P1 (fleet failover): WorkflowRunStore + completion-inbox PG twins (design doc in workflow-run-store-sql.ts).
@@ -234,7 +234,7 @@ export const PG_SCHEMA_STATEMENTS = [
      run           TEXT COLLATE "C"         NOT NULL,
      rev           INTEGER      NOT NULL DEFAULT 0,
      created_at_ms BIGINT       NOT NULL,
-     ended_at      BIGINT,
+     ended_at_ms   BIGINT,
      PRIMARY KEY (id)
    )`,
     `CREATE INDEX IF NOT EXISTS idx_wfrun_scope_created ON workflow_run (scope, created_at_ms)`,
@@ -279,8 +279,8 @@ export const PG_SCHEMA_STATEMENTS = [
      acked          SMALLINT     NOT NULL DEFAULT 0,
      source_task_id VARCHAR(191) COLLATE "C",
      principal      VARCHAR(190) COLLATE "C",
-     created_at     BIGINT       NOT NULL,
-     acked_at       BIGINT,
+     created_at_ms  BIGINT       NOT NULL,
+     acked_at_ms    BIGINT,
      PRIMARY KEY (run_id)
    )`,
     `CREATE INDEX IF NOT EXISTS idx_wfnotify_acked ON workflow_notify_journal (acked)`,

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

@@ -263,11 +263,11 @@ export declare class SqlRunStore {
      */
     reapSuspended(olderThanMs: number): Promise<number>;
     /**
-     * design/80 §3 inv#3 (crash-safe backstop — the run-row half of the checkpoint `terminal_at` sweep): fail a
+     * design/80 §3 inv#3 (crash-safe backstop — the run-row half of the checkpoint `terminal_at_ms` sweep): fail a
      * suspended run whose durable checkpoint was ALREADY EXPIRED by `reapExpired` (past its `deadline` or its
-     * absolute `terminal_at`), and release its task_active (unlock the session). Runs UNCONDITIONALLY (no
+     * absolute `terminal_at_ms`), and release its task_active (unlock the session). Runs UNCONDITIONALLY (no
      * approval-TTL gate), CHECKPOINT-STATE-driven not time-driven, so it aligns EXACTLY with the per-row
-     * `terminal_at` (which never falls before an operator's >30d deadline) — unlike a uniform timer, which would
+     * `terminal_at_ms` (which never falls before an operator's >30d deadline) — unlike a uniform timer, which would
      * either be inert (gated off at APPROVAL_TIMEOUT_SEC=0) or prematurely kill a long gate. Safe against the two
      * windows a naive predicate mis-fires on: (a) the transient suspend-write window — a run suspended before its
      * checkpoint row exists has NO expired checkpoint, so it is not matched; (b) a re-suspended session that minted

package/dist/plugins/run-store-sql.js

@@ -563,11 +563,11 @@ export class SqlRunStore {
         return reaped;
     }
     /**
-     * design/80 §3 inv#3 (crash-safe backstop — the run-row half of the checkpoint `terminal_at` sweep): fail a
+     * design/80 §3 inv#3 (crash-safe backstop — the run-row half of the checkpoint `terminal_at_ms` sweep): fail a
      * suspended run whose durable checkpoint was ALREADY EXPIRED by `reapExpired` (past its `deadline` or its
-     * absolute `terminal_at`), and release its task_active (unlock the session). Runs UNCONDITIONALLY (no
+     * absolute `terminal_at_ms`), and release its task_active (unlock the session). Runs UNCONDITIONALLY (no
      * approval-TTL gate), CHECKPOINT-STATE-driven not time-driven, so it aligns EXACTLY with the per-row
-     * `terminal_at` (which never falls before an operator's >30d deadline) — unlike a uniform timer, which would
+     * `terminal_at_ms` (which never falls before an operator's >30d deadline) — unlike a uniform timer, which would
      * either be inert (gated off at APPROVAL_TIMEOUT_SEC=0) or prematurely kill a long gate. Safe against the two
      * windows a naive predicate mis-fires on: (a) the transient suspend-write window — a run suspended before its
      * checkpoint row exists has NO expired checkpoint, so it is not matched; (b) a re-suspended session that minted

package/dist/plugins/tidb-pool.js

@@ -233,8 +233,8 @@ export const SCHEMA_STATEMENTS = [
      checkpoint   JSON         NOT NULL,
      outcome      JSON         NULL,
      deadline     BIGINT       NULL,
-     created_at   BIGINT       NOT NULL,
-     decided_at   BIGINT       NULL,
+     created_at_ms BIGINT      NOT NULL,
+     decided_at_ms BIGINT      NULL,
      -- rev (design/80 D-1): monotonic optimistic-concurrency counter bumped on every resolve/reopen, so a
      -- resolve(expect) requires the rev the resume observed to still be live → fail-closed on a concurrent
      -- resolve-reopen cycle (core → checkpoint.reopened_concurrently).
@@ -244,10 +244,10 @@ export const SCHEMA_STATEMENTS = [
      -- tool_unavailable (a fresh decision is allowed). Drives core's reopen-revote validation.
      -- NULL = NEVER REOPENED (the first resume is unconstrained).
      reopen_reason VARCHAR(32)  NULL,
-     -- terminal_at: crash-safe ABSOLUTE lifetime backstop (design/80 §3 inv#3), distinct from the per-approval
+     -- terminal_at_ms: crash-safe ABSOLUTE lifetime backstop (design/80 §3 inv#3), distinct from the per-approval
      -- deadline, stamped at put(). NULL on PRE-MIGRATION rows — those keep their DEADLINE-BASED expiry (the old
      -- path); the backstop only covers rows suspended after the column existed.
-     terminal_at  BIGINT       NULL,
+     terminal_at_ms BIGINT     NULL,
      -- gate_kind (design/80 D-D, SLA-timer): the CheckpointGate.kind, stamped at put(), so the SLA sweep splits by
      -- kind WITHOUT parsing the JSON blob per row — human/irreversible_ask past deadline are resolve-DENIED (the
      -- model continues with a denial), resource_limit/needs_review are abandonment-TTL → expire().
@@ -430,7 +430,7 @@ export const SCHEMA_STATEMENTS = [
      source_run_id VARCHAR(191) NOT NULL,
      scope         VARCHAR(190) NOT NULL,
      new_run_id    VARCHAR(191) NOT NULL,
-     claimed_at    BIGINT       NOT NULL,
+     claimed_at_ms BIGINT       NOT NULL,
      PRIMARY KEY (source_run_id, scope)
    ) COLLATE utf8mb4_bin`,
     // P1 (fleet failover, 2026-07-05): durable cross-replica WorkflowRunStore twin — one row per run, the full
@@ -443,7 +443,7 @@ export const SCHEMA_STATEMENTS = [
      run           MEDIUMTEXT   NOT NULL,
      rev           INT          NOT NULL DEFAULT 0,
      created_at_ms BIGINT       NOT NULL,
-     ended_at      BIGINT       NULL,
+     ended_at_ms   BIGINT       NULL,
      PRIMARY KEY (id),
      KEY idx_wfrun_scope_created (scope, created_at_ms),
      KEY idx_wfrun_scope_status (scope, status)
@@ -494,8 +494,8 @@ export const SCHEMA_STATEMENTS = [
      acked          TINYINT(1)   NOT NULL DEFAULT 0,
      source_task_id VARCHAR(191) NULL,
      principal      VARCHAR(190) NULL,
-     created_at     BIGINT       NOT NULL,
-     acked_at       BIGINT       NULL,
+     created_at_ms  BIGINT       NOT NULL,
+     acked_at_ms    BIGINT       NULL,
      PRIMARY KEY (run_id),
      KEY idx_wfnotify_acked (acked)
    ) COLLATE utf8mb4_bin`,

package/dist/plugins/workflow-journal-store-sql.d.ts

@@ -41,7 +41,7 @@ import { type SqlDriver } from "./sql-driver.js";
 /** Dual-dialect durable WorkflowJournalStore. See the file header for the dialect-delta ledger. */
 /** RB-242 租约旋钮。TTL 只是**崩溃兜底**(engine 终态 finally 显式释放;[1981]/[1984] 两层分工:
  *  engine 崩了没释放 ⇒ 陈旧 claim 可被接管)。
- *  🔴 缺省 1h,与 core file 参考实现同值([1984] :284)——**租约无心跳**(claimed_at 在授予时刻定格,
+ *  🔴 缺省 1h,与 core file 参考实现同值([1984] :284)——**租约无心跳**(claimed_at_ms 在授予时刻定格,
  *  运行期间不刷新),所以 TTL 必须盖过最长合法 run 时长:取小了(我初版 15min)会在一次 >TTL 的活跑
  *  中把 claim 判陈旧、放另一副本进来接管——恰是本缝要防的双跑。要更短的接管等待,先给 engine 半场
  *  加心跳刷新,再谈调小。 */
@@ -89,8 +89,8 @@ export declare class SqlWorkflowJournalStore implements WorkflowJournalStore {
      *  语义(bake-store `idem_key UNIQUE` 先例):PK (source_run_id, scope) 上的原子赢或观察。四步,每步
      *  单语句原子,并发交叉在任一步都收敛到「恰一个持有者」:
      *   ① 抢空位:INSERT..DO NOTHING / ON DUP KEY 无操作 —— affected=1 即赢;
-     *   ② 同持有者幂等重入(engine 重试同一 resume):按 (键, new_run_id) 守卫的 claimed_at 刷新;
-     *   ③ TTL 崩溃兜底接管:claimed_at < now-ttl 守卫下的原子改持有者(engine 终态会显式释放,
+     *   ② 同持有者幂等重入(engine 重试同一 resume):按 (键, new_run_id) 守卫的 claimed_at_ms 刷新;
+     *   ③ TTL 崩溃兜底接管:claimed_at_ms < now-ttl 守卫下的原子改持有者(engine 终态会显式释放,
      *     走到这步=上一持有 engine 崩了没释放;两层分工见 SqlWorkflowJournalStoreOptions 注);
      *   ④ 都没赢 ⇒ 读在位者返 {granted:false, holder}(holder 进 engine 的拒绝文案供归因)。 */
     resumeClaim(input: {

package/dist/plugins/workflow-journal-store-sql.js

@@ -76,8 +76,8 @@ export class SqlWorkflowJournalStore {
      *  语义(bake-store `idem_key UNIQUE` 先例):PK (source_run_id, scope) 上的原子赢或观察。四步,每步
      *  单语句原子,并发交叉在任一步都收敛到「恰一个持有者」:
      *   ① 抢空位:INSERT..DO NOTHING / ON DUP KEY 无操作 —— affected=1 即赢;
-     *   ② 同持有者幂等重入(engine 重试同一 resume):按 (键, new_run_id) 守卫的 claimed_at 刷新;
-     *   ③ TTL 崩溃兜底接管:claimed_at < now-ttl 守卫下的原子改持有者(engine 终态会显式释放,
+     *   ② 同持有者幂等重入(engine 重试同一 resume):按 (键, new_run_id) 守卫的 claimed_at_ms 刷新;
+     *   ③ TTL 崩溃兜底接管:claimed_at_ms < now-ttl 守卫下的原子改持有者(engine 终态会显式释放,
      *     走到这步=上一持有 engine 崩了没释放;两层分工见 SqlWorkflowJournalStoreOptions 注);
      *   ④ 都没赢 ⇒ 读在位者返 {granted:false, holder}(holder 进 engine 的拒绝文案供归因)。 */
     async resumeClaim(input) {
@@ -85,20 +85,20 @@ export class SqlWorkflowJournalStore {
         const ins = await this.db.query(this.q(
         // INSERT IGNORE(非 ON DUP KEY 无操作形):TiDB 对「无变化的 DUP KEY UPDATE」affected 报 1
         // (MySQL 报 0)——真双库跑出来的方言差;IGNORE 形两家都在冲突时报 0。
-        "INSERT IGNORE INTO workflow_resume_claim (source_run_id, scope, new_run_id, claimed_at) VALUES (?, ?, ?, ?)", "INSERT INTO workflow_resume_claim (source_run_id, scope, new_run_id, claimed_at) VALUES ($1, $2, $3, $4) ON CONFLICT (source_run_id, scope) DO NOTHING"), [input.sourceRunId, input.scope, input.newRunId, now]);
+        "INSERT IGNORE INTO workflow_resume_claim (source_run_id, scope, new_run_id, claimed_at_ms) VALUES (?, ?, ?, ?)", "INSERT INTO workflow_resume_claim (source_run_id, scope, new_run_id, claimed_at_ms) VALUES ($1, $2, $3, $4) ON CONFLICT (source_run_id, scope) DO NOTHING"), [input.sourceRunId, input.scope, input.newRunId, now]);
         if (ins.affected === 1)
             return { granted: true };
-        const refresh = await this.db.query(this.q("UPDATE workflow_resume_claim SET claimed_at = ? WHERE source_run_id = ? AND scope = ? AND new_run_id = ?", "UPDATE workflow_resume_claim SET claimed_at = $1 WHERE source_run_id = $2 AND scope = $3 AND new_run_id = $4"), [now, input.sourceRunId, input.scope, input.newRunId]);
+        const refresh = await this.db.query(this.q("UPDATE workflow_resume_claim SET claimed_at_ms = ? WHERE source_run_id = ? AND scope = ? AND new_run_id = ?", "UPDATE workflow_resume_claim SET claimed_at_ms = $1 WHERE source_run_id = $2 AND scope = $3 AND new_run_id = $4"), [now, input.sourceRunId, input.scope, input.newRunId]);
         if (refresh.affected >= 1)
             return { granted: true };
-        const takeover = await this.db.query(this.q("UPDATE workflow_resume_claim SET new_run_id = ?, claimed_at = ? WHERE source_run_id = ? AND scope = ? AND claimed_at < ?", "UPDATE workflow_resume_claim SET new_run_id = $1, claimed_at = $2 WHERE source_run_id = $3 AND scope = $4 AND claimed_at < $5"), [input.newRunId, now, input.sourceRunId, input.scope, now - this.resumeClaimTtlMs]);
+        const takeover = await this.db.query(this.q("UPDATE workflow_resume_claim SET new_run_id = ?, claimed_at_ms = ? WHERE source_run_id = ? AND scope = ? AND claimed_at_ms < ?", "UPDATE workflow_resume_claim SET new_run_id = $1, claimed_at_ms = $2 WHERE source_run_id = $3 AND scope = $4 AND claimed_at_ms < $5"), [input.newRunId, now, input.sourceRunId, input.scope, now - this.resumeClaimTtlMs]);
         if (takeover.affected >= 1)
             return { granted: true };
         const holder = await this.db.query(this.q("SELECT new_run_id FROM workflow_resume_claim WHERE source_run_id = ? AND scope = ?", "SELECT new_run_id FROM workflow_resume_claim WHERE source_run_id = $1 AND scope = $2"), [input.sourceRunId, input.scope]);
         // 行在①-③间被释放的窄窗:holder 读空 ⇒ 如实返 denied 无 holder(engine 下一次重试会在①赢)。
         const row = holder.rows[0];
         const holderId = row?.new_run_id === undefined ? undefined : String(row.new_run_id);
-        // ②的 UPDATE 在 MySQL 缺省协议下只数**被改变**的行——同毫秒重入(claimed_at 未变)会 affected=0
+        // ②的 UPDATE 在 MySQL 缺省协议下只数**被改变**的行——同毫秒重入(claimed_at_ms 未变)会 affected=0
         // 掉到这里;持有者==自己仍是 granted(幂等重入语义不依赖 affected 的方言细节)。
         if (holderId === input.newRunId)
             return { granted: true };

package/dist/plugins/workflow-run-store-sql.d.ts

@@ -12,7 +12,7 @@
  *
  * ## WorkflowRunStore twin
  * One row per run: the full `WorkflowRun` as a JSON blob + EXTRACTED columns for everything SQL needs to
- * index/filter (scope, status, created_at_ms, ended_at) + an authoritative `rev` column (the OCC key — the
+ * index/filter (scope, status, created_at_ms, ended_at_ms) + an authoritative `rev` column (the OCC key — the
  * blob's own `rev` is OVERLAID from the column on every read, so writes never have to know the bumped value
  * up front). `update` is a single-statement CAS (`WHERE id AND scope [AND rev]`, `SET rev = rev + 1`);
  * `listByScope` projects через core's SHARED `summarizeWorkflowRun` (anti-drift — identical to InMemory/File).

package/dist/plugins/workflow-run-store-sql.js

@@ -46,7 +46,7 @@ export class SqlWorkflowRunStore {
     async put(id, run) {
         const stored = { ...run, id, rev: run.rev ?? 0 }; // key authoritative + observed-rev base (InMemory parity)
         try {
-            await this.db.query(this.q("INSERT INTO workflow_run (id, scope, status, run, rev, created_at_ms, ended_at) VALUES (?,?,?,?,?,?,?)", "INSERT INTO workflow_run (id, scope, status, run, rev, created_at_ms, ended_at) VALUES ($1,$2,$3,$4,$5,$6,$7)"), [id, run.scope, run.status, JSON.stringify(stored), stored.rev, run.createdAt, run.endedAt ?? null]);
+            await this.db.query(this.q("INSERT INTO workflow_run (id, scope, status, run, rev, created_at_ms, ended_at_ms) VALUES (?,?,?,?,?,?,?)", "INSERT INTO workflow_run (id, scope, status, run, rev, created_at_ms, ended_at_ms) VALUES ($1,$2,$3,$4,$5,$6,$7)"), [id, run.scope, run.status, JSON.stringify(stored), stored.rev, run.createdAt, run.endedAt ?? null]);
         }
         catch (e) {
             // create-once error every backend throws (contract) — dup-key classification is dialect-specific:
@@ -83,7 +83,7 @@ export class SqlWorkflowRunStore {
                 return false; // even the skeleton is oversize — keep the prior revision
             blob = slim;
         }
-        const res = await this.db.query(this.q(`UPDATE workflow_run SET run = ?, rev = rev + 1, status = ?, ended_at = ? WHERE id = ? AND scope = ?${expect !== undefined ? " AND rev = ?" : ""}`, `UPDATE workflow_run SET run = $1, rev = rev + 1, status = $2, ended_at = $3 WHERE id = $4 AND scope = $5${expect !== undefined ? " AND rev = $6" : ""}`), expect !== undefined
+        const res = await this.db.query(this.q(`UPDATE workflow_run SET run = ?, rev = rev + 1, status = ?, ended_at_ms = ? WHERE id = ? AND scope = ?${expect !== undefined ? " AND rev = ?" : ""}`, `UPDATE workflow_run SET run = $1, rev = rev + 1, status = $2, ended_at_ms = $3 WHERE id = $4 AND scope = $5${expect !== undefined ? " AND rev = $6" : ""}`), expect !== undefined
             ? [blob, run.status, run.endedAt ?? null, id, scope, expect.rev]
             : [blob, run.status, run.endedAt ?? null, id, scope]);
         return res.affected === 1; // rev always bumps → affected is a faithful CAS verdict
@@ -156,12 +156,12 @@ export class SqlWorkflowRunStore {
             return 0; // retention is always explicit
         // Cheap columns only; terminal-set + keep-N semantics computed in JS to match InMemory EXACTLY
         // (isTerminalWorkflowStatus is core's — no status list duplicated into SQL).
-        const { rows } = await this.db.query(this.q("SELECT id, status, created_at_ms, ended_at FROM workflow_run WHERE scope = ? ORDER BY created_at_ms DESC, id DESC", "SELECT id, status, created_at_ms, ended_at FROM workflow_run WHERE scope = $1 ORDER BY created_at_ms DESC, id DESC"), [scope]);
+        const { rows } = await this.db.query(this.q("SELECT id, status, created_at_ms, ended_at_ms FROM workflow_run WHERE scope = ? ORDER BY created_at_ms DESC, id DESC", "SELECT id, status, created_at_ms, ended_at_ms FROM workflow_run WHERE scope = $1 ORDER BY created_at_ms DESC, id DESC"), [scope]);
         const terminal = rows.filter((r) => isTerminalWorkflowStatus(String(r.status)));
         const doomed = [];
         for (let i = 0; i < terminal.length; i++) {
             const r = terminal[i];
-            const anchor = r.ended_at != null ? Number(r.ended_at) : Number(r.created_at_ms);
+            const anchor = r.ended_at_ms != null ? Number(r.ended_at_ms) : Number(r.created_at_ms);
             const tooOld = opts.maxAgeMs !== undefined && anchor < now - opts.maxAgeMs;
             const overKeep = opts.keep !== undefined && i >= opts.keep;
             if (tooOld || overKeep)
@@ -311,31 +311,31 @@ export class SqlWorkflowNotifyJournalStore {
     async record(input) {
         // Idempotent-on-runId (a second record for the same run — incl. an acked one — is a no-op): TiDB
         // `INSERT IGNORE` vs PG `ON CONFLICT (run_id) DO NOTHING`.
-        await this.db.query(this.q("INSERT IGNORE INTO workflow_notify_journal (run_id, scope, acked, source_task_id, principal, created_at) VALUES (?,?,0,?,?,?)", "INSERT INTO workflow_notify_journal (run_id, scope, acked, source_task_id, principal, created_at) VALUES ($1,$2,0,$3,$4,$5) ON CONFLICT (run_id) DO NOTHING"), [input.runId, input.scope, input.sourceTaskId ?? null, input.principal ?? null, input.createdAt]);
+        await this.db.query(this.q("INSERT IGNORE INTO workflow_notify_journal (run_id, scope, acked, source_task_id, principal, created_at_ms) VALUES (?,?,0,?,?,?)", "INSERT INTO workflow_notify_journal (run_id, scope, acked, source_task_id, principal, created_at_ms) VALUES ($1,$2,0,$3,$4,$5) ON CONFLICT (run_id) DO NOTHING"), [input.runId, input.scope, input.sourceTaskId ?? null, input.principal ?? null, input.createdAt]);
     }
     async ack(runId, ackedAt) {
-        await this.db.query(this.q("UPDATE workflow_notify_journal SET acked = 1, acked_at = ? WHERE run_id = ? AND acked = 0", "UPDATE workflow_notify_journal SET acked = 1, acked_at = $1 WHERE run_id = $2 AND acked = 0"), [ackedAt, runId]);
+        await this.db.query(this.q("UPDATE workflow_notify_journal SET acked = 1, acked_at_ms = ? WHERE run_id = ? AND acked = 0", "UPDATE workflow_notify_journal SET acked = 1, acked_at_ms = $1 WHERE run_id = $2 AND acked = 0"), [ackedAt, runId]);
     }
     async listPending() {
-        const { rows } = await this.db.query("SELECT run_id, scope, source_task_id, principal, created_at FROM workflow_notify_journal WHERE acked = 0");
+        const { rows } = await this.db.query("SELECT run_id, scope, source_task_id, principal, created_at_ms FROM workflow_notify_journal WHERE acked = 0");
         return rows.map((r) => ({
             runId: String(r.run_id),
             scope: String(r.scope),
             acked: false,
             ...(r.source_task_id != null ? { sourceTaskId: String(r.source_task_id) } : {}),
             ...(r.principal != null ? { principal: String(r.principal) } : {}),
-            createdAt: Number(r.created_at),
+            createdAt: Number(r.created_at_ms),
         }));
     }
     /** Retention (same sweep as reapAllScopes): ACKED rows are pure history — without this the twin re-opens
      *  the unbounded-growth hole the same release closed for workflow_run. Pending rows are NEVER reaped (they
      *  are the recovery backlog; the orphan-grace sweep is what retires a stuck pending run). */
     async reapAcked(before) {
-        const res = await this.db.query(this.q("DELETE FROM workflow_notify_journal WHERE acked = 1 AND acked_at < ?", "DELETE FROM workflow_notify_journal WHERE acked = 1 AND acked_at < $1"), [before]);
+        const res = await this.db.query(this.q("DELETE FROM workflow_notify_journal WHERE acked = 1 AND acked_at_ms < ?", "DELETE FROM workflow_notify_journal WHERE acked = 1 AND acked_at_ms < $1"), [before]);
         return res.affected;
     }
     async get(runId) {
-        const { rows } = await this.db.query(this.q("SELECT run_id, scope, acked, source_task_id, principal, created_at, acked_at FROM workflow_notify_journal WHERE run_id = ?", "SELECT run_id, scope, acked, source_task_id, principal, created_at, acked_at FROM workflow_notify_journal WHERE run_id = $1"), [runId]);
+        const { rows } = await this.db.query(this.q("SELECT run_id, scope, acked, source_task_id, principal, created_at_ms, acked_at_ms FROM workflow_notify_journal WHERE run_id = ?", "SELECT run_id, scope, acked, source_task_id, principal, created_at_ms, acked_at_ms FROM workflow_notify_journal WHERE run_id = $1"), [runId]);
         const r = rows[0];
         if (!r)
             return null;
@@ -345,8 +345,8 @@ export class SqlWorkflowNotifyJournalStore {
             acked: Number(r.acked) === 1,
             ...(r.source_task_id != null ? { sourceTaskId: String(r.source_task_id) } : {}),
             ...(r.principal != null ? { principal: String(r.principal) } : {}),
-            createdAt: Number(r.created_at),
-            ...(r.acked_at != null ? { ackedAt: Number(r.acked_at) } : {}),
+            createdAt: Number(r.created_at_ms),
+            ...(r.acked_at_ms != null ? { ackedAt: Number(r.acked_at_ms) } : {}),
         };
     }
 }

package/dist/run-local.js

@@ -53,7 +53,7 @@ import { applyEffective, resolveMcpServers, mcpForScenario } from "./config-cent
 import { hostExecutionEnvFactory } from "./plugins/remote-env-host.js";
 import { makeLoadProjectMemory, makeProbeInstructionSources } from "./project-memory.js";
 import { loadSkills } from "./capabilities/skills.js";
-import { GiteaClient } from "./capabilities/repo-tools.js";
+import { createRepoClient } from "./capabilities/repo-tools.js";
 import { webSearchConfigFromEnv, createWebSearchBackend } from "./plugins/web-search.js";
 import { buildScenarios, selectScenario, centerScenarios } from "./capabilities/scenarios.js";
 import { pickHandsRunner, withoutExecutionEnv } from "./capabilities/hands-lane.js";
@@ -539,7 +539,7 @@ export async function runLocal(argv, deps = {}) {
     const handslessSubRunner = new Runner(withoutExecutionEnv(subRunnerDeps));
     // Capability layer (loadSkills + buildScenarios + selectScenario) — assembled exactly like main.ts.
     const skills = loadSkills(config.skillsDir);
-    const repoClient = config.gitApiBaseUrl ? new GiteaClient(config.gitApiBaseUrl, config.gitApiToken) : undefined;
+    const repoClient = config.gitApiBaseUrl ? createRepoClient(config.gitApiKind, config.gitApiBaseUrl, config.gitApiToken) : undefined;
     // systematic-audit: wire the env-configured WebSearch backend (WEB_SEARCH_PROVIDER) exactly like main.ts, so the
     // default scenario's WebSearch tool is assembled on the CLI path too (it was silently never built before).
     const webSearchCfg = webSearchConfigFromEnv();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/server",
-  "version": "7.9.0",
+  "version": "7.10.0",
   "description": "Sema Server — the server/API implementation layer for Sema, wiring core, registry, model providers, and cloud agent execution. Built on @sema-agent/core.",
   "type": "module",
   "license": "BUSL-1.1",