@sema-agent/server 7.79.3 → 7.80.1

package/dist/boot/stage-07-capability-layer.js

@@ -8,6 +8,7 @@ import { webSearchConfigFromEnv, createWebSearchBackend, shouldProbeWebSearchOnB
 import { createAuthorizer } from "../security.js";
 import { assertGateIntentServiceable, buildForceDurableGateInertNotice, hasOperatorGateIntent } from "../approval.js";
 import { loadSkills } from "../capabilities/skills.js";
+import { toolsRunOnThisHost } from "../task-cwd.js";
 import { createRepoClient } from "../capabilities/repo-tools.js";
 import { buildScenarios, builtinScenarioDetails } from "../capabilities/scenarios.js";
 import { RateLimiter } from "../observability/rate-limit.js";
@@ -108,7 +109,7 @@ export async function runStage07(ctx) {
         ? backend.rateLimiter(config.rateLimitPerMin, counterDegradeHook).startRefresh()
         : new RateLimiter(config.rateLimitPerMin);
     bindRateLimiter(rateLimiter);
-    let skills = loadSkills(config.skillsDir);
+    let skills = loadSkills(config.skillsDir, { toolsShareThisFilesystem: toolsRunOnThisHost(config) });
     skills = await configCenter.applyCenterCapabilities(skills);
     const repoClient = config.gitApiBaseUrl ? createRepoClient(config.gitApiKind, config.gitApiBaseUrl, config.gitApiToken) : undefined;
     const webSearchCfg = webSearchConfigFromEnv();

package/dist/capabilities/skills.d.ts

@@ -41,6 +41,16 @@ export interface LoadedSkill {
 export interface LoadSkillsOptions {
     /** 不可信 lane 的约束根(通常=clone root)。缺席=受控 lane,不做逐条目约束。 */
     confineTo?: string;
+    /**
+     * S-377 —— 「**工具跑的那台机器**的盘就是本进程这台盘吗」。真 ⇒ 目录形态技能带上自己的目录
+     * (`SkillSpec.baseDir`);假/缺席 ⇒ **不带**。判据的单一属主 = `task-cwd.ts` 的
+     * {@link import("../task-cwd.js").toolsRunOnThisHost}(调用方按它算,别在这里第二次判 lane)。
+     *
+     * 🔴 **缺席 = 不带**,是**故意的 fail-closed 方向**:带了一条工具那边不存在的路径,伤是「模型按它去
+     * 读、扑空,顺带看到本机目录布局」;不带的伤只是少一条线索(附件本来就随 invoke 全文内联投递,
+     * core 的律也明写缺席 ⇒ 结果逐字节与 baseDir 到货之前相同)。两个方向不对称 ⇒ 默认取轻的那边。
+     */
+    toolsShareThisFilesystem?: boolean;
 }
 /** `p` 的 realpath 必须落在 `rootReal` 之内(含自身),否则抛。`sep` 边界判定防 `/a/root-evil` 撞
  *  `/a/root` 前缀。目标不存在 ⇒ realpath 抛 ENOENT,同样是拒绝(悬空链接不该被读)。

package/dist/capabilities/skills.js

@@ -1,5 +1,5 @@
 import { readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
-import { join, sep } from "node:path";
+import { join, resolve, sep } from "node:path";
 export function assertConfined(p, rootReal, label = "skill entry") {
     let real;
     try {
@@ -59,6 +59,8 @@ export function loadSkills(dir, opts) {
             const files = collectAttachments(skillDir, "", confineRoot);
             if (files.length > 0)
                 skill.spec.files = files;
+            if (opts?.toolsShareThisFilesystem === true)
+                skill.spec.baseDir = resolve(skillDir);
             push(skill, join(skillDir, "SKILL.md"));
         }
     }

package/dist/http/admission.js

@@ -7,7 +7,7 @@ import { selfOrchestrationDenial } from "../task-workflow.js";
 import { centerEntitlementSourceWired } from "../runtime-caps-resolver.js";
 import { parseHooksConfig } from "../hooks/hook-runner.js";
 import { normalizeApproachNotice, unknownTaskAgentModelRef, validateTaskAgents } from "../spec-fields.js";
-import { isValidCwd, MAX_ADDITIONAL_DIRS } from "../task-cwd.js";
+import { isValidCwd, MAX_ADDITIONAL_DIRS, MAX_CWD_CHARS } from "../task-cwd.js";
 import { verifyRoundsFromBody } from "./verify-rounds.js";
 import { sendError, httpErrorCode } from "./send.js";
 export const MAX_SKILL_CONTENT_CHARS = 1_048_576;
@@ -27,6 +27,8 @@ export function validateUserSkills(skills) {
             return "skill.description must be a string";
         if (typeof s["content"] !== "string" || s["content"].length === 0 || s["content"].length > MAX_SKILL_CONTENT_CHARS)
             return `skill.content must be a non-empty string of at most ${MAX_SKILL_CONTENT_CHARS} characters (the engine rejects skills over this size outright at load time)`;
+        if (s["baseDir"] !== undefined && !isValidCwd(s["baseDir"]))
+            return `skill.baseDir must be an absolute path string of at most ${MAX_CWD_CHARS} characters with no ".." segment and no NUL byte (it is not resolved or read here — the engine only substitutes it into the skill's own text)`;
     }
     return null;
 }

package/dist/http/dispatch.js

@@ -2,9 +2,10 @@ import { createHash } from "node:crypto";
 import { setSsoPrincipal, ssoVerifiedPrincipal, setSsoScope, isDestructiveSessionWrite, PRINCIPAL_TOKEN_HEADER, APPROVAL_MAC_HEADER, APPROVAL_MAC_KID_HEADER } from "../security.js";
 import { publicStoreProbeError } from "../store-live-probe.js";
 import { looksLikeJwt } from "@sema-agent/settings-schema/api/auth-bridge";
-import { PRE_CREDENTIAL_ROUTES, POST_CREDENTIAL_ROUTES, routeLabel, isBillableSubmitPath, isCredentialGatedRewrite, isMethodDispatchedSubmitPath } from "./route-table.js";
+import { ROUTE_METHOD_ORDER } from "./route-ctx.js";
+import { PRE_CREDENTIAL_ROUTES, POST_CREDENTIAL_ROUTES, routeLabel, isBillableSubmitPath, isCredentialGatedRewrite, isMethodDispatchedSubmitPath, lookupRoute } from "./route-table.js";
 import { sendJson, sendError, isSseResponse } from "./send.js";
-import { authorized, systemFor } from "./principal-gate.js";
+import { authorized, systemFor, gatedPrincipal, sendPrincipalRefusal } from "./principal-gate.js";
 const PROCESS_STARTED_AT_MS = Date.now() - Math.round(process.uptime() * 1000);
 export function hasServiceAuth(config) {
     return Boolean(config.authToken) || Object.keys(config.authTokens ?? {}).length > 0;
@@ -42,19 +43,29 @@ export function createDispatch(ctx) {
         };
         deps.drainState.lastAttachEndedAt = () => lastAttachEndedAt;
     }
-    async function dispatchSegment(rows, req, res, url, ctx) {
+    async function dispatchSegment(rows, req, res, url, search, method, allow, ctx) {
         for (const row of rows) {
             if (row.enabled !== undefined && !row.enabled(deps))
                 continue;
-            if (await row.handler(req, res, url, ctx))
-                return true;
+            const found = lookupRoute(row.decls, url, method);
+            for (const m of found.allow)
+                if (!allow.includes(m))
+                    allow.push(m);
+            if (found.decl === null)
+                continue;
+            await row.handler(req, res, { decl: found.decl, params: found.params, search }, ctx);
+            return true;
         }
         return false;
     }
     async function handle(req, res) {
         const startedAt = Date.now();
         const method = req.method ?? "GET";
-        const url = (req.url ?? "/").split("?")[0];
+        const rawUrl = req.url ?? "/";
+        const qMark = rawUrl.indexOf("?");
+        const url = qMark === -1 ? rawUrl : rawUrl.slice(0, qMark);
+        const search = qMark === -1 ? "" : rawUrl.slice(qMark);
+        const allow = { pre: [], post: [] };
         noteActivity(url);
         const admitted = method !== "OPTIONS" && url !== "/health" && !url.startsWith("/metrics");
         if (admitted)
@@ -180,7 +191,7 @@ export function createDispatch(ctx) {
                 }
             }
         }
-        if (await dispatchSegment(PRE_CREDENTIAL_ROUTES, req, res, url, ctx))
+        if (await dispatchSegment(PRE_CREDENTIAL_ROUTES, req, res, url, search, method, allow.pre, ctx))
             return;
         let source = null;
         const anyServiceAuth = hasServiceAuth(deps.config);
@@ -221,8 +232,17 @@ export function createDispatch(ctx) {
             sendError(res, 503, "auth.service_token_required", "this worker requires a service auth token (set SERVICE_AUTH_TOKEN) before accepting destructive session writes (policy / sync-import / fork / delete)");
             return;
         }
-        if (await dispatchSegment(POST_CREDENTIAL_ROUTES, req, res, url, ctx))
+        if (await dispatchSegment(POST_CREDENTIAL_ROUTES, req, res, url, search, method, allow.post, ctx))
             return;
+        if (allow.pre.length > 0 || allow.post.length > 0) {
+            if (allow.post.length > 0 && deps.config.requirePrincipal && gatedPrincipal(req, deps.config) === undefined) {
+                sendPrincipalRefusal(res, req, deps.config);
+                return;
+            }
+            res.setHeader("allow", ROUTE_METHOD_ORDER.filter((m) => allow.pre.includes(m) || allow.post.includes(m)).join(", "));
+            sendError(res, 405, "method_not_allowed", "this path exists but not for this HTTP method — the `Allow` response header lists the methods it does answer");
+            return;
+        }
         sendError(res, 404, "not_found.route", "not found");
     }
     return { handle };

package/dist/http/resume-legs.js

@@ -1031,16 +1031,17 @@ export function createResumeLegs(ctx) {
     async function startFreshHostTurn(sessionId, objective, principal, req, trustedInternals, runId) {
         const cs = deps.checkpointStore;
         if (!deps.runStore) {
-            return { status: 501, body: { error: "delivering a workflow decision on the host's next turn requires a durable run store (DB_BACKEND=mysql|pg|local)", errorCode: "capability.run_store_required" } };
+            return { status: 501, body: { error: "delivering this decision requires a durable run store (DB_BACKEND=mysql|pg|local)", errorCode: "capability.run_store_required" } };
         }
         const ctx = await cs.getCtx(sessionId).catch(() => null);
         if (!ctx) {
             return {
                 status: 409,
                 body: {
-                    error: "the workflow's originating session no longer has the rebuild inputs for a new turn: a session's resume context is garbage-collected once it is stale AND that session itself has no pending checkpoint and no active run (REAP_RUN_STALE_SEC, default 120s) — a workflow CHILD's park does not hold the HOST session's row open. Raise REAP_RUN_STALE_SEC to cover how long approvals may sit before someone decides them, or resume the workflow run yourself with the runId below",
+                    error: "this approval waited too long to be delivered: the session this run was started from no longer keeps what a new turn would need, because that state is dropped once the session has been idle past this deployment's retention window (REAP_RUN_STALE_SEC — its current value is staleAfterSec below). Nothing was decided and the approval is still pending: resume the run yourself with the runId below, or ask whoever operates this deployment to raise REAP_RUN_STALE_SEC so approvals can sit longer before someone decides them",
                     errorCode: "conflict.resume_context_unavailable",
                     runId,
+                    staleAfterSec: deps.config.runStaleSec,
                 },
             };
         }
@@ -1108,7 +1109,7 @@ export function createResumeLegs(ctx) {
         }
         const gateKind = cp.gate?.kind;
         if (gateKind !== "task_done") {
-            return { status: 409, body: { error: `cannot wake: this checkpoint awaits a pending gate decision (gate "${gateKind ?? "unknown"}") — resolve it through its own decide entry`, errorCode: "wake.gate_pending" } };
+            return { status: 409, body: { error: `cannot wake: this session is waiting on a pending gate decision (gate "${gateKind ?? "unknown"}") — resolve it through its own decide entry`, errorCode: "wake.gate_pending" } };
         }
         const trusted = operator;
         if (message !== undefined) {

package/dist/http/route-ctx.d.ts

@@ -426,11 +426,107 @@ export interface RouteCtxBase {
 export interface RouteCtx extends RouteCtxBase {
     req: RouteRequestState;
 }
-export type RouteHandler = (req: IncomingMessage, res: ServerResponse, url: string, ctx: RouteCtx) => Promise<boolean>;
-/** 域实现的收尾闩:见文件头「已处理」语义。 */
-export interface RouteMiss {
-    fell: boolean;
+/**
+ * 域入口的签名(S-146 第三刀 车②)。
+ *
+ * 🔴 **`url` 与「已处理」布尔一并删掉**,零别名([ref] 硬 breaking):分派器已经**匹配过一次**并把
+ * 结果整个交进来(`match`),所以一只 handler 既不需要再判路,也不可能「没匹配上」——「返回 false
+ * 放过给下一域」那一形在第三刀之后结构上不存在(路径归属由声明表一次定死),留着一个恒为 true 的
+ * 返回值就是给它留门。域内的 `RouteMiss` 闩随之删除。
+ *
+ * 阀门(`RouteRow.enabled`)是唯一的「本域今天不在」通道,它在**匹配之前**判,请求落到分派器尾的
+ * 全局 404(诚实缺席,不是 501)。
+ */
+export type RouteHandler<Id extends string = string> = (req: IncomingMessage, res: ServerResponse, match: RouteMatch<Id>, ctx: RouteCtx) => Promise<void>;
+/**
+ * 分派结果 —— handler 能看到的**全部**路由事实。
+ *
+ * · `decl`   命中的那一行(`id` 是域内闭集词:handler `switch (match.decl.id)` + `assertNever`,漏一口 = 编译红);
+ * · `params` 匹配式**具名捕获组** → 段值。没参与匹配的可选组**不入表**(值缺席),与旧 `m[i]` 的
+ *            `undefined` 同形 —— 所以必填段照旧写 `!`,可选段照旧判 `undefined`;
+ * · `search` 原始查询串(`"?a=b"` 或 `""`)。域内取查询参数一律 `new URLSearchParams(match.search)`:
+ *            与旧的 `new URL(req.url ?? "", "http://x").searchParams` **逐字同义**(前导 `?` 与百分号
+ *            解码的处置相同),但读的是分派器已经剖好的那一份,而不是让每只域再从 `req.url` 剖一遍。
+ *            🔴 `req.url` / `req.method` 自此不进任何域的判路 —— `test/route-shape-roster.test.ts`
+ *            的反向格(域内判路必须为零)是它的机器钉。
+ */
+export interface RouteMatch<Id extends string = string> {
+    readonly decl: RouteDispatchDecl & {
+        readonly id: Id;
+    };
+    readonly params: Readonly<Record<string, string | undefined>>;
+    readonly search: string;
 }
+/** 一张 `X_ROUTES` 里**可分派**行的 `id` 闭集(纯门行没有 `id`,不进这只并集)。 */
+export type RouteIdsOf<T extends readonly RouteDecl[]> = Extract<T[number], {
+    readonly id: string;
+}>["id"];
+/**
+ * 闭集 `switch` 的收尾臂([ref] 形):所有 `id` 都被 `case` 吃掉之后,这里的实参类型是 `never` ——
+ * 漏一口就是**编译红**。运行期到得了这一行只可能是有人绕过类型把野值塞进了声明表,所以它**响**
+ * (抛),不静默 200 也不静默 404。
+ */
+export declare function assertNever(x: never): never;
+/** 改写门是**方法感知**的(它的撤销动词是 DELETE)。闭集 —— 加第五个动词是编译红。 */
+export type RouteMethod = "GET" | "POST" | "PUT" | "DELETE";
+/** 闭集的**规范序**(405 的 `Allow` 头按它排,于是同一条路径的头字节恒定,不随声明序抖)。
+ *  `satisfies` 让它与 {@link RouteMethod} 双向闭合:漏一个动词 / 多一个都是编译红。 */
+export declare const ROUTE_METHOD_ORDER: readonly ["GET", "POST", "PUT", "DELETE"];
+export interface RouteDeclFacts {
+    /** 「这条 url **烧模型**」—— drain / model-roster-pending / 无 service-token 三道 503 的共同判别。
+     *  没有这一列 = 不烧模型(零默认值:要它为真必须显式写出来,漏写的方向是**少收一笔账单**而不是
+     *  少一道门 —— 反了才是灾难,所以三道门读的是 true 这一侧)。 */
+    readonly billable?: true;
+    /** 「本条 url 在**没有任何 service credential** 的部署形下,这几个方法必须 fail-closed」。
+     *  判据(两个合取项)= 「授权的唯一输入是 principal 头」∧「持久改写,或爆炸半径跨租户的治理读」;
+     *  逐口论证在各 `routes/*.ts` 的头注里,声明行只记结论。 */
+    readonly credentialGated?: readonly RouteMethod[];
+    /** 「这条 url **是**计费提交面,但它到底提不提交由**请求体里的方法**决定」—— 单 URL 多方法的
+     *  JSON-RPC 端点。两道**可用性** 503(drain / roster-pending)按 url 一刀切会把同端点上的纯读一起
+     *  关掉,所以分派器对本行**跳过**那两道,改由域模块在写分支里施加同样的两道(文案逐字同源)。
+     *  🔴 只豁免那两道,**不豁免安全轴**:`billable` 本身仍为 true,无 service token 那道 fail-closed
+     *  503 照旧罩着(它判的是「这台机能不能收写」,与方法无关,且必须在解析请求体之前)。 */
+    readonly methodDispatched?: true;
+}
+/** **可分派行**多出来的两列(S-146 第三刀):身份 + 它真认的方法。纯门行两列都没有(见下)。 */
+interface RouteDeclIdentity {
+    /** **全表唯一**的行名(kebab 闭集词)。这是声明行的身份:域 handler 用
+     *  `switch (match.decl.id)` 闭集分派(漏一口 = 编译红),所以它必须稳定、唯一、且与路径解耦
+     *  (路径会改形,身份不该跟着改)。全表唯一性由 `test/route-shape-roster.test.ts` 层A 的良构格钉住。 */
+    readonly id: string;
+    /** 本行真被响应的 HTTP 方法 —— 车② 起它是**分派器**的方法判据:路径命中而方法不在列 ⇒ 分派器
+     *  统一 405 + `Allow`(并集按**路径**取,跨行跨域),handler 一个字都不再判方法。
+     *
+     *  🔴 因此本列必须是**逐口真值**,不能是并集。车② 为此做了两件事(改前的两条结构性口径,原文在
+     *     车① 的本注里):① 5 条「一行覆盖多条子路径、各子路径方法集不同」的并集行按动词拆成逐口行
+     *     (`session-verb` / `run-subagent-verb` / `run-task-verb` / `session-sync-verb` / `session-sync-blobs`);
+     *     ② 2 条「一条路径住着两只域」的跨域行按方法拆成两行各归各域(`/v1/tasks` = trace-usage 的 GET +
+     *     tasks 的 POST;`/v1/memory/export` = memory-policy 的 GET + memory-bundle 的 POST)。 */
+    readonly methods: readonly RouteMethod[];
+}
+/**
+ * **可分派行**:一条真路由。匹配式二选一 —— `path`(精确;标签**就是** path 自身,所以没有 label 列,
+ * 少一处手抄)或 `pattern`(形状;捕获组一律**具名**,段值经 `RouteMatch.params` 交给 handler)。
+ */
+export type RouteDispatchDecl = (RouteDeclFacts & RouteDeclIdentity & {
+    readonly path: string;
+}) | (RouteDeclFacts & RouteDeclIdentity & {
+    readonly pattern: RegExp;
+    readonly label?: string;
+});
+/**
+ * **纯门行**(facts-only):一段前缀上的门性质,**不是路由**。
+ *
+ * 🔴 它刻意比任何标签行都宽(`/v1/devices/` 下将来长出的任何写动词天然在改写门内),正因为宽,它
+ * **不可分派**:型上就没有 `id` 也没有 `methods` —— 于是「分派器会不会拿一条门行去应答请求」这个
+ * 问题在类型上就不存在,不靠谁记得在 `if` 里排除它。它只喂三只门谓词与 `routeLabel`。
+ */
+export type RouteGateDecl = RouteDeclFacts & {
+    readonly prefix: string;
+    readonly label?: string;
+};
+/** 一张声明表的行 = 可分派行 ∪ 纯门行(闭集)。 */
+export type RouteDecl = RouteDispatchDecl | RouteGateDecl;
 /**
  * [ref]([ref] 存在性 oracle 封口)——`not_found.run` 的**唯一**文案源,unknown 与 not-yours 两臂共用。
  * 修前:unknown 臂发这条长指路文案、not-yours 臂发短文「run not found」,同 code 下按**文案长度**即可
@@ -456,4 +552,5 @@ export declare function acceptedResumingReceipt(taskId: string, sessionId: strin
 export declare const RUN_NOT_FOUND_MESSAGE = "run not found \u2014 the id belongs to no run in this deployment's run store (a run from another server process, or an in-memory store that did not survive a restart, is not visible here)";
 /** [ref] 前缀=域判别子既成契约:a\* 与 wa\* 形 id 给 TaskOutput/journal 指路;其余给 {@link RUN_NOT_FOUND_MESSAGE}。 */
 export declare function runNotFoundMessage(id: string): string;
+export {};
 //# sourceMappingURL=route-ctx.d.ts.map

package/dist/http/route-ctx.js

@@ -17,6 +17,10 @@ export function sendResumeOutcome(res, out, logger, extraBody) {
         res.setHeader("retry-after", String(Math.ceil(wait)));
     sendJson(res, out.status, extraBody === undefined ? out.body : { ...out.body, ...extraBody });
 }
+export function assertNever(x) {
+    throw new Error(`unreachable route id: ${String(x)}`);
+}
+export const ROUTE_METHOD_ORDER = ["GET", "POST", "PUT", "DELETE"];
 export function acceptedResumingReceipt(taskId, sessionId) {
     return { status: 200, body: { taskId, sessionId, status: "resuming", bindingEnforced: true } };
 }

package/dist/http/route-table.d.ts

@@ -18,9 +18,18 @@
  *  · `ROUTES` —— **行序 = 分派序**,`position` 说它在全局服务凭据门的哪一侧。门不再「按行号插在链中间」,
  *    而是在 `pre` 段与 `post` 段之间**恒定一处**执行 ⇒ ① 与 ② 合一(名册就是分派序本身,两者再不可能漂),
  *    那道「从 handle() 源码抽序对拍」的门随之删掉 —— 不是放松,是它守的事变成了结构上不可违反。
- *    ⚠️ 刻意**不引入 matcher**:handler 自己判 url 这一点一个字不动(改它等于重写 34 个域模块的判路)。
- *  · `ROUTE_DECLARATIONS` —— ③④⑤ 合成一张;一行声明它的匹配式与它**真有**的性质
- *    (`billable` / `credentialGated` / `methodDispatched`),没有该性质就不写那一列(零默认值)。
+ *    🔴 S-146 第三刀 车②:**matcher 落地**。一行多了 `decls` 一列(本域真应答的口集合),而
+ *    `ROUTE_DECLARATIONS` 就是这一列按行序摊平 ⇒「分派表」与「声明表」从此是同一份数据的两个投影,
+ *    不再是两份要对拍的名单;域 handler 不再看 url / method(见 route-ctx.ts `RouteHandler` 头注)。
+ *  · `ROUTE_DECLARATIONS` —— ③④⑤ 合成一张;一行声明它的 `id`(全表唯一身份)、匹配式、它**真被响应**
+ *    的 `methods`、以及它**真有**的性质(`billable` / `credentialGated` / `methodDispatched`),
+ *    没有该性质就不写那一列(零默认值)。
+ *    🔴 S-146 第三刀 车①:这 115 行的**行本体搬回各域**(`routes/x.ts` 的 `X_ROUTES`)—— 路径的
+ *    单一属主与 `*_PATH` 常量今天的属主对齐,本文件只做拼接与查找结构。`RouteDecl` / `RouteMethod`
+ *    两个类型住在 `route-ctx.js`(域模块本来就 import 的那只接缝模块),理由见那里的行注。
+ *    车②:行分两族 —— **可分派行**(`path` / `pattern`,带 `id` + `methods`)与**纯门行**
+ *    (`prefix`,facts-only,型上就没有 `id`/`methods`),于是「门行会不会被当成路由应答」这个问题
+ *    在类型上就不存在。
  *
  * 判据两条,逐字:
  *  · **标签取首命中**(优先序):精确行先于形状行([[ref]] 的结论,这里是结构性的而不是靠行序),
@@ -29,24 +38,36 @@
  *    `||` 的逐字同义,也是「前缀行比标签行宽」这件事的正解(`/v1/devices/` 下将来长出的任何写动词
  *    天然在改写门内,不必等谁想起来补一行标签)。
  *
- * 新增一条路由 = 新建 `routes/x.ts` + 本表加一行(+ `test/route-order-freeze.test.ts` 的冻结表加一行,
- * 那是 position 的外部对拍源)。`position` 与匹配式都是必填 —— 忘了就是**编译红**,不是静默 404。
+ * 新增一条路由 = 新建 `routes/x.ts` + **该域自己的 `X_ROUTES` 加一行** + 本表的拼接列表加一段
+ * (+ `test/route-order-freeze.test.ts` 的冻结表加一行,那是 position 的外部对拍源)。
+ * `position` / `id` / `methods` / 匹配式都是必填 —— 忘了就是**编译红**,不是静默 404。
  *
  * 🔴 **旧禁令已解除**:标签表此前必须「写字面量不引常量」、注释里不许出现某两个字符 —— 那是两道
  * 扫源码文本的门反向塑形源码的产物(它们的捕获正则抓不到常量、非贪婪捕获会被那对字符提前截断)。
  * 两道门都改成读本表之后,这条禁令没有了对象,随它的 11 处行注一并删;要引常量就引(`routes/*.ts`
  * 的 `*_PATH` 常量本来就是那些路径的单一属主)。
  *
- * 🔴 本文件是**叶模块**:只 import `routes/*.ts` 的 handler 与几只单源正则、以及类型。组合根与流水线
+ * 🔴 本文件是**叶模块**:只 import `routes/*.ts` 的 handler 与 `X_ROUTES`、以及类型。组合根与流水线
  * (`server.ts` / `dispatch.ts`)一律反过来 import 它,值边单向,`test/module-cycle-gate.test.ts` 看守。
+ * 反向的**类型**边也没有:`RouteDecl` 住在 `route-ctx.js`,域模块 import 的是它,不是本文件。
  */
 import type { FlatServiceDeps } from "./server.js";
-import type { RouteHandler } from "./route-ctx.js";
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { RouteDecl, RouteDispatchDecl, RouteMatch, RouteCtx, RouteMethod } from "./route-ctx.js";
 /** 一只域 handler 相对**全局服务凭据门**的位置。门前 = 未鉴权可达(每一只都要单独论证),门后 = 先过凭据。 */
 export type RoutePosition = "pre-credential" | "post-credential";
 export interface RouteRow {
-    /** 域入口(`routes/*.ts` 的 `handleX`)。签名一致性是编译期钉:入口漂了形 = 编译红,不是运行时静默 404。 */
-    readonly handler: RouteHandler;
+    /** 域入口(`routes/*.ts` 的 `handleX`)。签名一致性是编译期钉:入口漂了形 = 编译红,不是运行时静默 404。
+     *
+     *  🔴 **方法式**声明(不是 `handler: RouteHandler`):方法式的参数位是**双变**的,于是一只只认自己
+     *  那几个 `id` 的域入口(`RouteHandler<"a" | "b">`)能落进这张宽表,而域内那只闭集 `switch` 仍按它
+     *  自己的窄 union 判穷尽。窄↔宽的**绑定**由 {@link row} 工厂在编译期钉死:`decls` 与 `handler` 配错
+     *  (把 B 域的表配给 A 域的入口)就是红,不是运行期的静默全不命中。 */
+    handler(req: IncomingMessage, res: ServerResponse, match: RouteMatch, ctx: RouteCtx): Promise<void>;
+    /** 本域**真应答的那些口**(S-146 第三刀 车②)—— 一行 ROUTES = 一只域入口 = 它的口集合。
+     *  `ROUTE_DECLARATIONS` 就是这一列按行序摊平,所以「声明表」与「分派表」再不可能是两份名单:
+     *  一只域忘了挂自己的声明 = 它一个口都分派不到,当场全红,而不是静默漂一行。 */
+    readonly decls: readonly RouteDecl[];
     /** 必填 —— 新增路由必须**显式**决定它在凭据门的哪一侧。 */
     readonly position: RoutePosition;
     /** 域名(kebab;= `routes/` 下的模块名)。评审把本表当「域全集」读时它是那份清单的名字列,
@@ -62,42 +83,33 @@ export declare const ROUTES: readonly RouteRow[];
  *  「门前行不许出现在门后行之后」由 `test/route-order-freeze.test.ts` 钉住。 */
 export declare const PRE_CREDENTIAL_ROUTES: readonly RouteRow[];
 export declare const POST_CREDENTIAL_ROUTES: readonly RouteRow[];
-/** 改写门是**方法感知**的(它的撤销动词是 DELETE)。闭集 —— 加第五个动词是编译红。 */
-export type RouteMethod = "GET" | "POST" | "PUT" | "DELETE";
-interface RouteDeclFacts {
-    /** 「这条 url **烧模型**」—— drain / model-roster-pending / 无 service-token 三道 503 的共同判别。
-     *  没有这一列 = 不烧模型(零默认值:要它为真必须显式写出来,漏写的方向是**少收一笔账单**而不是
-     *  少一道门 —— 反了才是灾难,所以三道门读的是 true 这一侧)。 */
-    readonly billable?: true;
-    /** 「本条 url 在**没有任何 service credential** 的部署形下,这几个方法必须 fail-closed」。
-     *  判据(两个合取项)= 「授权的唯一输入是 principal 头」∧「持久改写,或爆炸半径跨租户的治理读」;
-     *  逐口论证在各 `routes/*.ts` 的头注里,本表只记结论。 */
-    readonly credentialGated?: readonly RouteMethod[];
-    /** 「这条 url **是**计费提交面,但它到底提不提交由**请求体里的方法**决定」—— 单 URL 多方法的
-     *  JSON-RPC 端点。两道**可用性** 503(drain / roster-pending)按 url 一刀切会把同端点上的纯读一起
-     *  关掉,所以分派器对本行**跳过**那两道,改由域模块在写分支里施加同样的两道(文案逐字同源)。
-     *  🔴 只豁免那两道,**不豁免安全轴**:`billable` 本身仍为 true,无 service token 那道 fail-closed
-     *  503 照旧罩着(它判的是「这台机能不能收写」,与方法无关,且必须在解析请求体之前)。 */
-    readonly methodDispatched?: true;
-}
 /**
- * 一行的匹配式三选一(闭集;`path` 行的标签**就是** path 自身,所以它没有 label 列 —— 少一处手抄)。
- * `prefix` 与 `pattern` 行的 label 可缺席:那是**纯门行**(比标签行宽,只供门的并集判据),
- * 缺席 ⇒ 本行不铸任何标签。
+ * 全表 = 流水线四行 + **每一行 `ROUTES` 自己的 `decls`**,按行序摊平。
+ *
+ * 🔴 车② 之前这里是一张手写的 `...X_ROUTES` 拼接列表,而它与 `ROUTES` 是**两份**按同一条口径排的
+ *    名单(「域首次出现的位置」),漏一段 / 排错序都只在标签面才看得见。现在拼接就是 `ROUTES` 的投影:
+ *    `a2a-serve.ts` / `workflows.ts` / `runs.ts` 三只文件各占两行域入口,车② 把它们的 `X_ROUTES`
+ *    **按行拆成两只数组**各归各行(`A2A_SERVE_ROUTES`/`A2A_RPC_ROUTES`、`WORKFLOWS_ROUTES`/
+ *    `WORKFLOW_AGENT_STEER_ROUTES`、`RUNS_ROUTES`/`RUN_VERBS_ROUTES`)—— 于是「一行域入口 = 一组口」
+ *    这句话没有例外,拼接列表这件手抄活儿随之消失。
+ *
+ * 🔴 顺序的判据只有一条:**形状行取首命中**(精确行由 `LABEL_BY_PATH` 先查,前缀行不铸标签 ⇒ 两者
+ *    与序无关)。按域重排后形状行的相对序确实变了(例如 `SESSION_WAKE_RE` 从 `$verb` 行之前挪到了
+ *    之后),但每一对「重排后跨了身位」的形状行都**互不重叠**或**同标签**,所以 `routeLabel` 的
+ *    像逐字未变 —— 这不是靠读出来的,是 `test/route-match-parity.test.ts` 的 `labels` 金样逐格钉住的。
+ *
+ * 🔴 由 `test/route-shape-roster.test.ts` 层A 看守:本表每一行的样本经 `routeLabel` 必须落非 "other",
+ *    且标签静态段与样本逐段吻合、族段不是占位符。新路由不补本表 ⇒ 那门当场红并点名。
  */
-export type RouteDecl = (RouteDeclFacts & {
-    readonly path: string;
-}) | (RouteDeclFacts & {
-    readonly prefix: string;
-    readonly label?: string;
-}) | (RouteDeclFacts & {
-    readonly pattern: RegExp;
-    readonly label?: string;
-});
-/** 🔴 由 `test/route-shape-roster.test.ts` 棘轮看守:门机器枚举 `src/http/**` 的全部路由模式并断言每条
- *  都映射到非 "other"——新路由不补本表该门当场红(census 抓获本表曾漂掉 56 条模式:session-sync/workspace/
- *  workflows/subagents/attachments/images/leader 等整族全折 "other",metrics 不可分桶)。 */
 export declare const ROUTE_DECLARATIONS: readonly RouteDecl[];
+/**
+ * **匹配一次**(S-146 第三刀 车②)—— 一条可分派行对一条 url:命中 ⇒ 具名捕获组表,不命中 ⇒ `null`。
+ *
+ * 🔴 `null` 与 `{}` 是**两件事**(`{}` = 命中且无参),所以返回值不是 `Record | undefined`。
+ * 没参与匹配的可选组不入表(`m.groups` 里它们是 `undefined`,原样留着 —— 域内判「这一段在不在」
+ * 读的就是这个 `undefined`,与改前 `m[i] === undefined` 逐字同形)。
+ */
+export declare function matchDecl(d: RouteDispatchDecl, url: string): Readonly<Record<string, string | undefined>> | null;
 /** Stable, low-cardinality route label for metrics/logs (ids collapsed to `:id`). */
 export declare function routeLabel(_method: string, url: string): string;
 /** POST endpoints that trigger BILLABLE work — the fail-closed auth guard must cover ALL of them. */
@@ -109,5 +121,21 @@ export declare function isBillableSubmitPath(url: string): boolean;
 export declare function isCredentialGatedRewrite(method: string, url: string): boolean;
 /** 见 `RouteDeclFacts.methodDispatched` 的头注(单 URL 多方法端点)。 */
 export declare function isMethodDispatchedSubmitPath(url: string): boolean;
-export {};
+/** 一次分派查找的结果:命中的行与它的参数,外加**这条路径上所有行**的方法并集(405 的 `Allow`)。 */
+export interface RouteLookup {
+    /** 方法也对上了 ⇒ 这一行;路径对上了但方法都不在 ⇒ `null`(调用方据 {@link allow} 发 405)。 */
+    readonly decl: RouteDispatchDecl | null;
+    readonly params: Readonly<Record<string, string | undefined>>;
+    /** 本段里**路径**命中的每一行的 `methods` 并集(按声明序去重;空 = 这条路径在本段一行都不占)。 */
+    readonly allow: readonly RouteMethod[];
+}
+/**
+ * 在一组可分派行里按「**精确 → 形状**,同类按声明序」找路径命中,再按方法过滤。
+ *
+ * 🔴 **路径命中不等于就是它**:方法不在这一行的 `methods` 里就继续往后找(`GET /v1/images/bakes`
+ * 落 `image-by-profile` 而不是只认 `POST` 的 `image-bake-submit`,与改前域内 if 链的落点逐字同)。
+ * 全部路径命中行的方法并集就是 `Allow` —— 并集按**路径**取而不是按行,所以同一条路径住着两只域时
+ * (`/v1/tasks` 的 GET 在 trace-usage、POST 在 tasks)405 的 `Allow` 是两行之和。
+ */
+export declare function lookupRoute(decls: readonly RouteDecl[], url: string, method: string): RouteLookup;
 //# sourceMappingURL=route-table.d.ts.map