@sema-agent/server 7.87.3 → 7.88.1

package/dist/http/durable-run-leg.js

@@ -4,6 +4,7 @@ import { fleetRunPublisher, fleetRunLabels } from "../fleet/fleet-bus.js";
 import { cascadeConfig, runMeta } from "./run-meta.js";
 import { resolveStreamApprovalGate } from "../tool-approval.js";
 import { buildActiveRunConflict } from "./active-run-conflict.js";
+import { commitPlacement, devicePlacementErrorBody } from "./device-placement.js";
 import { clearTurnActivity, readTurnActivityMs } from "../turn-activity.js";
 import { recordResourceWindow } from "../resource-window.js";
 export async function mintAndDriveDurableRun(ctx, runStore, args) {
@@ -24,6 +25,9 @@ export async function mintAndDriveDurableRun(ctx, runStore, args) {
         }
         return { status: 409, body: await buildActiveRunConflict({ runStore, checkpointStore: deps.checkpointStore, governance: deps.config, runStaleSec: deps.config.runStaleSec, turnActivity: readTurnActivityMs }, sessionId, created.activeTaskId) };
     }
+    const placementReject = await commitPlacement(deps, runStore, taskId, args.prepared.bindingIntent);
+    if (placementReject)
+        return { status: placementReject.status, body: devicePlacementErrorBody(placementReject) };
     if (deps.checkpointStore) {
         await deps.checkpointStore.putCtx(sessionId, { body: args.prepared.body, memoryScope: args.prepared.auth?.memoryScope });
     }

package/dist/http/resume-legs.js

@@ -32,6 +32,7 @@ import { createSessionSyncLocal } from "./routes/session-sync.js";
 import { createImagesLocal } from "./routes/images.js";
 import { gatedPrincipal, explicitOperatorOk } from "./principal-gate.js";
 import { buildActiveRunConflict, resumeEntryForGate } from "./active-run-conflict.js";
+import { commitPlacement, devicePlacementErrorBody } from "./device-placement.js";
 import { ASK_USER_QUESTION_TOOL_NAME } from "../approval-content-kind.js";
 function isCheckpointReopenedFailure(r) {
     const code = failureCodeOf(r.terminal);
@@ -394,6 +395,9 @@ export function createResumeLegs(ctx) {
             if (!created.ok) {
                 return { status: 409, body: await buildActiveRunConflict({ runStore: deps.runStore, checkpointStore: deps.checkpointStore, governance: deps.config, runStaleSec: deps.config.runStaleSec, turnActivity: readTurnActivityMs }, sessionId, created.activeTaskId) };
             }
+            const placementReject = await commitPlacement(deps, deps.runStore, freshId, undefined);
+            if (placementReject)
+                return { status: placementReject.status, body: devicePlacementErrorBody(placementReject) };
             taskId = freshId;
             freshRunClaimed = true;
         }

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

@@ -127,6 +127,14 @@ export interface PreparedTaskSubmission {
      *  装配跑在这条腿的通告口开张之前,所以铸点交不出去 —— 由腿在 `registerEngineNoticeLeg` 那一拍
      *  经 `pending` 一起投(投递单点仍是那一只注册助手,不新开第二条机制)。缺席 = 本次装配没铸下任何通告。 */
     engineNotices?: readonly EngineNotice[];
+    /**
+     * S-470(device lane 首绑写协议,design §4.3.2 两阶段 placement)—— **已校验、未写库**的 placement 意图。
+     *
+     * 缺席的两种含义都等价于「本腿没有 placement 要提交」:①本部署不是 device 车道(绝大多数);
+     * ②本腿不是 fresh 根提交(resume 家族根本不经 `prepareSpec`)。在场 ⇒ 每个 `runStore.createRun(`
+     * 成功点**必须**把它交给 `commitPlacement`(唯一写入属主;类级机器门钉住每个调用点都接了)。
+     */
+    bindingIntent?: import("./device-placement.js").DevicePlacementIntent;
 }
 /**
  * 一条会话的**续跑重建输入**(`checkpoint_ctx` 的行体)—— 提交腿写一次,续跑腿读它重建 spec。

package/dist/http/routes/capabilities.js

@@ -66,7 +66,7 @@ export async function handleCapabilities(req, res, match, ctx) {
                 approvals: Boolean(deps.checkpointStore),
                 sessions: Boolean(deps.sessionAudit),
                 deviceExecutor: deps.deviceHub
-                    ? { enabled: true, protocolVersion: DEVICE_PROTOCOL_VERSION, maxInflightPerDevice: deps.config.remoteExec?.provider === "device" ? (deps.config.remoteExec.maxInflightPerDevice ?? 4) : 4, wsPath: DEVICE_WS_PATH }
+                    ? { enabled: true, protocolVersion: DEVICE_PROTOCOL_VERSION, maxInflightPerDevice: deps.config.remoteExec?.provider === "device" ? (deps.config.remoteExec.maxInflightPerDevice ?? 4) : 4, wsPath: DEVICE_WS_PATH, management: Boolean(deps.deviceStore && deps.deviceEnrollment) }
                     : false,
                 sessionEvents: Boolean(deps.sessionWatch && deps.sessionStorage?.getLeafId && deps.sessionStorage?.ownerOf),
                 fleet: deps.fleetBus

package/dist/http/routes/devices.d.ts

@@ -33,8 +33,9 @@
  * `ssoVerifiedScope`(registry-JWT 的 `scope` claim,security.ts:同为签名真源、非自报头)。两者齐备
  * 才构成一个 device 域;缺 tenant claim 的凭据(纯 principal 头 / 静态 token 直连)**判不出域** ⇒
  * 非 operator 一律响亮 403(fail-closed + loud,[ref]:静默空列表是假健康)——基线稿对 enrollment 的
- * 同向裁定是「缺 tenant/global scope 明确拒注册」。将来的 enrollment/管理端点(车C 余件)**必须**从
- * 这同一个函数取域,不得手抄第二份派生。
+ * 同向裁定是「缺 tenant/global scope 明确拒注册」。enrollment/管理端点与**首绑写协议**都从
+ * 这同一个函数取域(S-470 起它住在 `http/device-placement.ts` —— 提交腿也要用,放在路由域里是层序倒挂),
+ * 不得手抄第二份派生。
  *
  * ── 反枚举 404 的单一铸造点 ──────────────────────────────────────────────────────────────────────
  * 「绑定不在 / 不是你的 / 目标设备不在 / 不是该域的 / 已吊销」五臂共用 {@link sendDeviceNotFound} ——
@@ -54,18 +55,27 @@
  */
 import type { IncomingMessage, ServerResponse } from "node:http";
 import type { RouteCtx, RouteMatch, RouteIdsOf } from "../route-ctx.js";
-import { type DeviceOwner } from "../../device-store.js";
-/**
- * 调用方 device 域的**唯一铸造点**(文件头注)。undefined = 判不出域(无 principal,或无 tenant
- * claim)——消费点必须走 explicit operator 或响亮 403,禁静默空视图。
- */
-export declare function deviceOwnerDomainOf(req: IncomingMessage, config: RouteCtx["deps"]["config"]): DeviceOwner | undefined;
 export declare function handleDevices(req: IncomingMessage, res: ServerResponse, match: RouteMatch<DevicesRouteId>, ctx: RouteCtx): Promise<void>;
 export declare const DEVICES_ROUTES: readonly [{
     readonly id: "devices-list";
     readonly path: "/v1/devices";
     readonly credentialGated: readonly ["GET"];
     readonly methods: readonly ["GET"];
+}, {
+    readonly id: "device-enroll-tokens";
+    readonly path: "/v1/devices/enroll-tokens";
+    readonly credentialGated: readonly ["POST"];
+    readonly methods: readonly ["POST"];
+}, {
+    readonly id: "device-enroll";
+    readonly path: "/v1/devices/enroll";
+    readonly credentialGated: readonly ["POST"];
+    readonly methods: readonly ["POST"];
+}, {
+    readonly id: "device-revoke";
+    readonly pattern: RegExp;
+    readonly label: "/v1/devices/:deviceId/revoke";
+    readonly methods: readonly ["POST"];
 }, {
     readonly id: "device-session-rebind";
     readonly pattern: RegExp;

package/dist/http/routes/devices.js

@@ -1,8 +1,10 @@
 import { sendError, sendJson } from "../send.js";
 import { explicitOperatorOk, gatedPrincipal, sendPrincipalRefusal } from "../principal-gate.js";
 import { assertNever } from "../route-ctx.js";
-import { ssoVerifiedScope } from "../../security.js";
-import { assertDeviceIdShape, assertRootSessionIdShape, sameDeviceOwner, } from "../../device-store.js";
+import { DEVICE_PLATFORM_OS, DEVICE_PUBKEY_MAX_BYTES, DEVICE_TEXT_LIMITS, assertDeviceIdShape, assertDevicePubkeyShape, assertRootSessionIdShape, sameDeviceOwner, } from "../../device-store.js";
+import { DEFAULT_ENROLL_TOKEN_TTL_SEC } from "../../device-enrollment.js";
+import { deviceOwnerDomainOf } from "../device-placement.js";
+import { echoKeyName } from "../../request-key-closure.js";
 const DEVICE_NOT_FOUND_MESSAGE = "device not found";
 const NO_DEVICE_DOMAIN_MESSAGE = "device management needs a caller domain: this credential carries no verified tenant scope claim (registry auth-bridge JWT `scope`) and is not an explicit operator — connect through the registry auth bridge, or configure OPERATOR_PRINCIPALS";
 const DEVICE_LANE_REQUIRED_MESSAGE = "device management requires the device execution lane (REMOTE_EXEC=device with a SQL store backend) — this deployment has no device lane wired";
@@ -11,15 +13,6 @@ void _deviceRouteCodesPinned;
 function sendDeviceNotFound(res) {
     sendError(res, 404, "not_found.device", DEVICE_NOT_FOUND_MESSAGE);
 }
-export function deviceOwnerDomainOf(req, config) {
-    const subject = gatedPrincipal(req, config);
-    if (subject === undefined)
-        return undefined;
-    const tenant = ssoVerifiedScope(req);
-    if (tenant === undefined)
-        return undefined;
-    return { tenant, subject };
-}
 function wellFormedKey(assert, v) {
     try {
         assert(v);
@@ -40,11 +33,95 @@ function deviceListRow(row, online) {
 function boundDeviceOf(row) {
     return { deviceId: row.deviceId, rev: row.rev, boundAt: new Date(row.boundAtMs).toISOString() };
 }
+function sendDeviceRejection(res, rej) {
+    if (rej.retryAfterSec !== undefined)
+        res.setHeader("retry-after", String(rej.retryAfterSec));
+    sendError(res, rej.status, rej.code, rej.message);
+}
+function bodyKeyIssue(body, accepted) {
+    const extra = Object.keys(body).filter((k) => !accepted.includes(k)).map((k) => echoKeyName("", k)).sort();
+    if (extra.length === 0)
+        return null;
+    return `unknown key(s) in body: ${extra.join(", ")} — this endpoint accepts ${accepted.length === 0 ? "no body keys" : accepted.slice().sort().join(", ")} (a silently dropped key is a declaration that never existed)`;
+}
+async function readClosedBody(req, res, readJson, accepted) {
+    let body;
+    try {
+        body = await readJson(req);
+    }
+    catch {
+        sendError(res, 400, "request.invalid_json", "invalid JSON body");
+        return null;
+    }
+    if (typeof body !== "object" || body === null || Array.isArray(body)) {
+        sendError(res, 400, "request.body_shape", "body must be a JSON object");
+        return null;
+    }
+    const issue = bodyKeyIssue(body, accepted);
+    if (issue !== null) {
+        sendError(res, 400, "request.body_shape", issue);
+        return null;
+    }
+    return body;
+}
+const ENROLL_BODY_KEYS = ["token", "pubkey", "platformOs", "platformArch", "displayName", "workspaceRoot"];
+function parseEnrollBody(res, body) {
+    const str = (k, required) => {
+        const v = body[k];
+        if (v === undefined)
+            return required ? (sendError(res, 400, "request.body_shape", `${k} is required`), null) : "";
+        if (typeof v !== "string")
+            return sendError(res, 400, "request.field_invalid", `${k} must be a string`), null;
+        return v;
+    };
+    const token = str("token", true);
+    if (token === null)
+        return null;
+    const pubkey = str("pubkey", true);
+    if (pubkey === null)
+        return null;
+    const platformArch = str("platformArch", false);
+    if (platformArch === null)
+        return null;
+    const displayName = str("displayName", false);
+    if (displayName === null)
+        return null;
+    const workspaceRoot = str("workspaceRoot", true);
+    if (workspaceRoot === null)
+        return null;
+    const os = DEVICE_PLATFORM_OS.find((o) => o === body.platformOs);
+    if (os === undefined) {
+        sendError(res, 400, "request.field_invalid", `platformOs must be one of ${DEVICE_PLATFORM_OS.join(" | ")} (v1 closed set — win32 is not supported yet, and is never silently accepted as a third value)`);
+        return null;
+    }
+    if (token.length === 0 || token.length > 256) {
+        sendError(res, 400, "request.field_invalid", "token must be a non-empty string of at most 256 characters");
+        return null;
+    }
+    if (!wellFormedKey(assertDevicePubkeyShape, pubkey)) {
+        sendError(res, 400, "request.field_invalid", `pubkey is not a valid device public key (byte-exact key: non-empty, no control characters or surrounding whitespace, at most ${DEVICE_PUBKEY_MAX_BYTES} bytes)`);
+        return null;
+    }
+    for (const [k, v, max] of [["displayName", displayName, DEVICE_TEXT_LIMITS.displayName], ["platformArch", platformArch, DEVICE_TEXT_LIMITS.platformArch], ["workspaceRoot", workspaceRoot, DEVICE_TEXT_LIMITS.workspaceRoot]]) {
+        if (Buffer.byteLength(v, "utf8") > max) {
+            sendError(res, 400, "request.field_invalid", `${k} exceeds the ${max}-byte column (a silently truncated value is a different value — refusing at the door)`);
+            return null;
+        }
+    }
+    if (workspaceRoot.length === 0) {
+        sendError(res, 400, "request.field_invalid", "workspaceRoot is required and must be non-empty (it is the device-side root every instruction resolves against)");
+        return null;
+    }
+    return { token: token, pubkey: pubkey, platformOs: os, platformArch: platformArch, displayName: displayName, workspaceRoot: workspaceRoot };
+}
 export async function handleDevices(req, res, match, ctx) {
     switch (match.decl.id) {
         case "devices-list":
         case "device-session":
         case "device-session-rebind":
+        case "device-enroll-tokens":
+        case "device-enroll":
+        case "device-revoke":
             break;
         default:
             return assertNever(match.decl.id);
@@ -58,7 +135,8 @@ export async function handleDevices(req, res, match, ctx) {
     }
     const store = deps.deviceStore;
     const hub = deps.deviceHub;
-    if (!store || !hub) {
+    const enrollment = deps.deviceEnrollment;
+    if (!store || !hub || !enrollment) {
         sendError(res, 501, "capability.device_lane_required", DEVICE_LANE_REQUIRED_MESSAGE);
         return;
     }
@@ -74,6 +152,88 @@ export async function handleDevices(req, res, match, ctx) {
         sendJson(res, 200, { devices: rows.filter((r) => r.status !== "revoked").map((r) => deviceListRow(r, online)) });
         return;
     }
+    if (match.decl.id === "device-enroll-tokens") {
+        if (domain === undefined) {
+            sendError(res, 403, "auth.forbidden", NO_DEVICE_DOMAIN_MESSAGE);
+            return;
+        }
+        if ((await readClosedBody(req, res, readJson, [])) === null)
+            return;
+        const ttlSeconds = (deps.config.remoteExec?.provider === "device" ? deps.config.remoteExec.enrollTokenTtlSec : undefined) ?? DEFAULT_ENROLL_TOKEN_TTL_SEC;
+        const issued = await enrollment.issueEnrollToken({ target: domain, createdBy: domain.subject, ttlSeconds });
+        if (!issued.ok) {
+            sendDeviceRejection(res, issued.reject);
+            return;
+        }
+        sendJson(res, 200, { token: issued.value.token, expiresAt: new Date(issued.value.row.expiresAtMs).toISOString(), ttlSec: ttlSeconds });
+        return;
+    }
+    if (match.decl.id === "device-enroll") {
+        if (domain === undefined) {
+            sendError(res, 403, "auth.forbidden", NO_DEVICE_DOMAIN_MESSAGE);
+            return;
+        }
+        const raw = await readClosedBody(req, res, readJson, ENROLL_BODY_KEYS);
+        if (raw === null)
+            return;
+        const body = parseEnrollBody(res, raw);
+        if (body === null)
+            return;
+        const outcome = await enrollment.enroll({
+            token: body.token,
+            requester: domain,
+            device: { displayName: body.displayName, platformOs: body.platformOs, platformArch: body.platformArch, pubkey: body.pubkey, workspaceRoot: body.workspaceRoot },
+        });
+        if (!outcome.ok) {
+            sendDeviceRejection(res, outcome.reject);
+            return;
+        }
+        sendJson(res, 200, { deviceId: outcome.value.device.deviceId });
+        return;
+    }
+    if (match.decl.id === "device-revoke") {
+        const decodedId = safeDecode(match.params.deviceId);
+        if (decodedId === null) {
+            sendError(res, 400, "request.path_malformed", "device id segment is not valid percent-encoding");
+            return;
+        }
+        if (!wellFormedKey(assertDeviceIdShape, decodedId)) {
+            sendError(res, 400, "request.id_invalid", "invalid device id segment (device keys are byte-exact: non-empty, no control characters or surrounding whitespace, at most 64 bytes)");
+            return;
+        }
+        if (!operator && domain === undefined) {
+            sendError(res, 403, "auth.forbidden", NO_DEVICE_DOMAIN_MESSAGE);
+            return;
+        }
+        const body = await readClosedBody(req, res, readJson, ["reason"]);
+        if (body === null)
+            return;
+        const reason = body.reason;
+        if (reason !== undefined && (typeof reason !== "string" || Buffer.byteLength(reason, "utf8") > DEVICE_TEXT_LIMITS.revokeReason)) {
+            sendError(res, 400, "request.field_invalid", `reason must be a string of at most ${DEVICE_TEXT_LIMITS.revokeReason} bytes (a silently truncated audit reason is a different reason)`);
+            return;
+        }
+        let owner;
+        if (operator) {
+            const row = await store.getDeviceUnscoped(decodedId);
+            if (!row) {
+                sendDeviceNotFound(res);
+                return;
+            }
+            owner = row.owner;
+        }
+        else {
+            owner = domain;
+        }
+        const revoked = await enrollment.revoke({ deviceId: decodedId, requester: owner, revokedBy: principal ?? owner.subject, reason: reason === undefined ? null : reason });
+        if (!revoked.ok) {
+            sendDeviceRejection(res, revoked.reject);
+            return;
+        }
+        await hub.fenceDevice(decodedId).catch((err) => deps.logger?.warn("device_revoke_fence_failed", { deviceId: decodedId, err: err instanceof Error ? err.message : String(err) }));
+        sendJson(res, 200, { deviceId: revoked.value.deviceId, status: revoked.value.status, ...(revoked.value.revokedAtMs !== null ? { revokedAt: new Date(revoked.value.revokedAtMs).toISOString() } : {}) });
+        return;
+    }
     const decoded = safeDecode(match.params.rootSessionId);
     if (decoded === null) {
         sendError(res, 400, "request.path_malformed", "session id segment is not valid percent-encoding");
@@ -164,6 +324,9 @@ export async function handleDevices(req, res, match, ctx) {
 }
 export const DEVICES_ROUTES = [
     { id: "devices-list", path: "/v1/devices", credentialGated: ["GET"], methods: ["GET"] },
+    { id: "device-enroll-tokens", path: "/v1/devices/enroll-tokens", credentialGated: ["POST"], methods: ["POST"] },
+    { id: "device-enroll", path: "/v1/devices/enroll", credentialGated: ["POST"], methods: ["POST"] },
+    { id: "device-revoke", pattern: /^\/v1\/devices\/(?<deviceId>[^/]+)\/revoke$/, label: "/v1/devices/:deviceId/revoke", methods: ["POST"] },
     { id: "device-session-rebind", pattern: /^\/v1\/devices\/sessions\/(?<rootSessionId>[^/]+)\/rebind$/, label: "/v1/devices/sessions/:id/rebind", methods: ["POST"] },
     { id: "device-session", pattern: /^\/v1\/devices\/sessions\/(?<rootSessionId>[^/]+)$/, label: "/v1/devices/sessions/:id", credentialGated: ["GET"], methods: ["GET"] },
     { prefix: "/v1/devices/", credentialGated: ["POST"] },

package/dist/http/routes/tasks.js

@@ -21,6 +21,7 @@ import { collectSsePreamble } from "../sse-log.js";
 import { buildApprovalPreamble, buildApprovalPreambleSseFrames } from "../../approval-card.js";
 import { createApprovalCardEmitter, resolveApprovalLeg, resolveStreamApprovalGate } from "../../tool-approval.js";
 import { buildActiveRunConflict, toDoneFrameResult } from "../active-run-conflict.js";
+import { commitPlacement, devicePlacementErrorBody } from "../device-placement.js";
 import { headerStr, gatedPrincipal, explicitOperatorOk } from "../principal-gate.js";
 import { failOpenTagForDroppedFrame, recordFailOpen } from "../../observability/fail-open.js";
 import { assertNever } from "../route-ctx.js";
@@ -226,6 +227,12 @@ export async function handleTasks(req, res, match, ctx) {
                         sseData(res, { type: "done", result: toDoneFrameResult(conflict) });
                         return { status: 409, body: conflict };
                     }
+                    const placementReject = await commitPlacement(deps, deps.runStore, tid, prepared.bindingIntent);
+                    if (placementReject) {
+                        const body = devicePlacementErrorBody(placementReject);
+                        sseData(res, { type: "done", result: { status: "failed", errorCode: body.errorCode, errorMessage: body.error } });
+                        return { status: placementReject.status, body };
+                    }
                     durableTaskId = tid;
                 }
                 if (prepared.spec.sessionId)
@@ -771,6 +778,9 @@ export async function handleTasks(req, res, match, ctx) {
                         recordResourceWindow(tid, prepared.spec.resourceSuspend);
                     if (!created.ok)
                         return { status: 409, body: await buildActiveRunConflict({ runStore: deps.runStore, checkpointStore: deps.checkpointStore, governance: deps.config, runStaleSec: deps.config.runStaleSec, turnActivity: readTurnActivityMs }, prepared.spec.sessionId, created.activeTaskId) };
+                    const placementReject = await commitPlacement(deps, deps.runStore, tid, prepared.bindingIntent);
+                    if (placementReject)
+                        return { status: placementReject.status, body: devicePlacementErrorBody(placementReject) };
                     deps.sessionTitler?.maybeTitle(prepared.spec.sessionId, prepared.spec.objective, typeof prepared.spec.model === "string" ? prepared.spec.model : prepared.spec.model?.id);
                     durableTaskId = tid;
                 }

package/dist/http/server.d.ts

@@ -304,6 +304,19 @@ export interface ServiceSeamDeps {
      * v2 换绑稿 §7)。
      */
     deviceStore?: import("../device-store.js").DeviceStore;
+    /**
+     * S-470(车C 余件):device lane 的**准入链**(`createDeviceEnrollment`)—— 管理面三个写动词
+     * (签发 / 注册 / 吊销)与首绑写协议(`commitPlacement`)的**唯一**判据属主。
+     *
+     * 🔴 为什么路由拿的是它而不是 {@link deviceStore}:enrollment 那一层持着两件路由造不出来的东西 ——
+     * ①跨副本限速座(`DeviceEnrollRateLimiter`,§7-T5 ⑤:端点车**必须**传一个,而它由 boot 从既有
+     * `RateGate` 适配);②反枚举拒绝的**单一铸造点**(四种 enrollment 失败理由在 wire 上逐字节同形)。
+     * 路由若绕过它直接打店,那两件就会在路由里被手抄第二份 —— 而手抄的那份迟早漏一臂。
+     *
+     * 与 {@link deviceStore} / {@link deviceHub} **同源装配**(`boot/device-lane.ts` 一处建齐三件),
+     * 所以三者的在场性是同一个事实;族内 501 谓词因此可以是「三件齐」这一句话。
+     */
+    deviceEnrollment?: import("../device-enrollment.js").DeviceEnrollment;
     /** Audit回溯: current context (+ summary) for a session, plus its owner. Enables GET /v1/sessions/:id. */
     sessionAudit?: (sessionId: string) => Promise<({
         owner: string | null;

package/dist/http/wire-types.d.ts

@@ -362,6 +362,21 @@ export interface TaskRequestBody {
      *  (a caller can't point a shared/cloud worker at an arbitrary host path). Validated absolute (prepareSpec 400s a
      *  relative cwd — it would silently resolve against the SERVICE process cwd). */
     cwd?: string;
+    /**
+     * S-470(device lane 首绑写协议,design `device-executor-lane-v2` §4.3.2)—— 这条**根会话**要执行在
+     * 哪台已注册的员工设备上(`POST /v1/devices/enroll` 返回的 `dev_<ulid>`)。
+     *
+     * 与 {@link cwd} **同级同信任姿势**:调用方供给、server 闸裁 —— 它不是身份,身份恒取验证过的
+     * 复合身份链;它只是「在我自己名下的设备里挑一台」。
+     *  · 仅 `REMOTE_EXEC=device` 的部署接受;其它车道收到它 = **400 响亮拒**(不静默忽略 —— 调用方会
+     *    以为自己指定了执行设备,而那条声明从未存在);
+     *  · 仅**根任务**提交携带(子代无条件继承根绑定,core 为 subagent/cascade/verify 另铸 sessionId);
+     *  · 首绑 = INSERT-if-absent CAS(并发单赢家);后续根提交:缺席 = 沿用绑定 / 携且同 = 幂等 /
+     *    携且异 = 403 `device.identity_mismatch`(**v1 无隐式重绑**,换设备走
+     *    `POST /v1/devices/sessions/:rootSessionId/rebind`);
+     *  · resume 家族(`/decide` / `/answer` / `/plan_review` / `/wake`)**不收**这个键:车道随树固定。
+     */
+    deviceId?: string;
     /** [ref] (CC `--add-dir`, core `TaskSpec.additionalDirectories`): extra host dirs the FILE tools may reach
      *  beyond the containment root. 🔒 Gated exactly like `cwd`/`shellEnv` — honored ONLY on the single-user host
      *  lane (`task-cwd.ts` `cwdHonored`); off that lane `boot/resolve-spec.ts` drops them with a loud

package/dist/model-route-url.d.ts

@@ -0,0 +1,15 @@
+/** 机读码(拼法随 `config.<键名蛇形>_*` 既有族:`config.model_provider_invalid` / `config.retention_policy_invalid`)。 */
+export declare const GATEWAY_URL_USERINFO_CODE = "config.gateway_url_userinfo";
+/** 这个 URL 带 userinfo(用户名或密码任一非空)吗?解析不动 ⇒ `false`(「不是 URL」由别的门管,本条只判凭据位)。 */
+export declare function urlCarriesUserinfo(raw: string): boolean;
+/**
+ * 模型路由 base URL 的拒因(`undefined` = 这一位合法)。
+ *
+ * 拒因四件齐:**码** + **哪个 env 键** + **洗过的 URL**(host/port/path 逐字,userinfo 与凭据参数成记号 ——
+ * 运维要靠 host 认出是哪一条路由,而密码一个字节都不许进启动错误)+ **出路一句**(点名真实旋钮)。
+ *
+ * @param envKey 出问题的那根 env 旋钮的名字(CSV 键上还带第几项)。
+ * @param credentialKnob 这条路由把凭据放哪儿 —— 出路一句点名的旋钮名。
+ */
+export declare function modelRouteUrlRefusal(envKey: string, raw: string, credentialKnob: string): string | undefined;
+//# sourceMappingURL=model-route-url.d.ts.map

package/dist/model-route-url.js

@@ -0,0 +1,19 @@
+import { buildDisplaySafeUrl } from "./trace/redact.js";
+export const GATEWAY_URL_USERINFO_CODE = "config.gateway_url_userinfo";
+export function urlCarriesUserinfo(raw) {
+    if (raw === "" || !URL.canParse(raw))
+        return false;
+    const u = new URL(raw);
+    return u.username !== "" || u.password !== "";
+}
+export function modelRouteUrlRefusal(envKey, raw, credentialKnob) {
+    if (!urlCarriesUserinfo(raw))
+        return undefined;
+    return (`env ${envKey} carries credentials in the URL userinfo (${buildDisplaySafeUrl(raw)}) [${GATEWAY_URL_USERINFO_CODE}] — ` +
+        "WHATWG forbids constructing a fetch Request from a URL with credentials, so EVERY model call on this route " +
+        "fails deterministically at request-construction time (it used to look like a slow network flake: the error was " +
+        "retried for ~3 minutes before surfacing). " +
+        `Put the credential in ${credentialKnob} (or the matching header knob) instead of the URL, and keep the URL to ` +
+        "scheme/host/port/path.");
+}
+//# sourceMappingURL=model-route-url.js.map

package/dist/observability/fail-open.d.ts

@@ -305,6 +305,15 @@ export interface FailOpenRecorderDeps {
     seedWarned?: ReadonlySet<FailOpenTag>;
     seedBacklog?: ReadonlyMap<FailOpenTag, number>;
     seedLogged?: ReadonlySet<FailOpenTag>;
+    /**
+     * `detail` 落探针文件前的脱敏器(装配层注入 `trace/redact.ts` 的 `redactSecrets`)。
+     *
+     * 🔴 **缺席 ⇒ detail 原文不落盘,只落 tag + 一个「为何扣下」的标记**(fail-closed 且响亮);脱敏器抛 ⇒ 同。理由:探针行是本模块**唯一**
+     * 把调用方文本写到盘上的地方,而三十多个调用方里不少传的是异常文本 —— 异常文本里带网关 URL、URL 的 query 里带
+     * `api_key=` 都是常态。「不放密钥」此前只是 {@link recordFailOpen} 注释里的一句自觉,现在是这一个铸点上的结构。
+     * 用注入而不是直接 import:脱敏器自己 import 了本模块(它有一条 fail-open 留痕臂),直接 import 会成环。
+     */
+    redactDetail?: (detail: string) => string;
     /** 测试注入:替掉 stderr 契约行的落点。缺省直写 `process.stderr`。 */
     writeStderr?: (line: string) => void;
     /** 测试注入:替掉探针文件追加。缺省 `appendFileSync`(同步=进程猝死也不丢已记的行)。 */
@@ -320,7 +329,8 @@ export declare function createFailOpenRecorder(deps?: FailOpenRecorderDeps): Fai
  *  - `seedLogged` —— 已真发出去的结构化 warn 不重发;没发过的由新 logger 补一条。
  */
 export declare function installFailOpenRecorder(deps: Omit<FailOpenRecorderDeps, "seedCounts" | "seedWarned" | "seedBacklog" | "seedLogged">): FailOpenRecorder;
-/** 兜底臂的调用口。`tag` 必须已登记(闭集类型),`detail` 是可选的一行现场(路径/原因,不放密钥)。 */
+/** 兜底臂的调用口。`tag` 必须已登记(闭集类型),`detail` 是可选的一行现场(路径/原因)。落盘前由记录器统一脱敏
+ *  ({@link FailOpenRecorderDeps.redactDetail});调用方仍不该**刻意**往里放密钥,但不再靠这句自觉兜底。 */
 export declare function recordFailOpen(tag: FailOpenTag, detail?: string): void;
 /** 本进程各 tag 累计次数——`/metrics` 之外的进程内读数(测试与自检面用)。 */
 export declare function failOpenCounts(): ReadonlyMap<FailOpenTag, number>;

package/dist/observability/fail-open.js

@@ -283,6 +283,7 @@ export function createFailOpenRecorder(deps = {}) {
     }
     return {
         record: (tag, detail) => {
+            const safeDetail = renderDetail(detail, deps.redactDetail);
             const entry = FAIL_OPEN_TAGS[tag];
             counts.set(tag, (counts.get(tag) ?? 0) + 1);
             if (deps.metrics === undefined) {
@@ -298,14 +299,14 @@ export function createFailOpenRecorder(deps = {}) {
             }
             if (probePath !== undefined && probePath !== "") {
                 try {
-                    appendProbe(probePath, `fail-open ${tag}${detail !== undefined && detail !== "" ? ` ${detail}` : ""}\n`);
+                    appendProbe(probePath, `fail-open ${tag}${safeDetail === undefined ? "" : ` ${safeDetail}`}\n`);
                 }
                 catch {
                 }
             }
             if (deps.logger !== undefined && !logged.has(tag)) {
                 try {
-                    deps.logger.warn("fail_open", { tag, cls: entry.cls, note: entry.note, ...(detail !== undefined ? { detail } : {}) });
+                    deps.logger.warn("fail_open", { tag, cls: entry.cls, note: entry.note, ...(safeDetail !== undefined ? { detail: safeDetail } : {}) });
                     logged.add(tag);
                 }
                 catch {
@@ -327,6 +328,21 @@ export function createFailOpenRecorder(deps = {}) {
     };
 }
 let current = createFailOpenRecorder();
+function renderDetail(detail, redactDetail) {
+    if (detail === undefined || detail === "")
+        return undefined;
+    if (redactDetail === undefined)
+        return "[detail withheld: no redactor installed]";
+    let safe;
+    try {
+        safe = redactDetail(detail);
+    }
+    catch (err) {
+        return `[detail withheld: redactor threw ${err instanceof Error ? err.name : typeof err}]`;
+    }
+    const oneLine = safe.replace(/[\r\n]+/g, " ");
+    return oneLine === "" ? undefined : oneLine;
+}
 export function installFailOpenRecorder(deps) {
     current = createFailOpenRecorder({
         ...deps,

package/dist/request-key-closure.js

@@ -20,7 +20,7 @@ export function keyClosureClause(names, label) {
 const TASK_BODY_DECLARED_KEYS = [
     "a2aPeers", "acceptPartialRestore", "additionalDirectories", "additionalReadDirectories", "agents",
     "appendSystemPrompt", "attachmentIds", "attachments", "capabilitiesNeeded", "cascade", "clientContext",
-    "compaction", "compactionModel", "council", "cwd", "debate", "deferTools", "enableFork", "excludeTools",
+    "compaction", "compactionModel", "council", "cwd", "debate", "deferTools", "deviceId", "enableFork", "excludeTools",
     "finalVerification", "forwardSubagentEvents", "images", "interactiveTools", "jobId", "limits", "maxCostUsd",
     "maxTokens", "mcpServers", "memory", "memoryCapture", "memoryWrite", "model", "objective", "oneShot", "outputRetries",
     "outputSchema", "permissionMode", "projectId", "promptProfile", "reasoningEffort", "requireExistingSession",

package/dist/run-local.js

@@ -43,6 +43,7 @@ import { createKeyResolver } from "./key-resolver.js";
 import { createLogger } from "./observability/logger.js";
 import { createMetrics } from "./observability/metrics.js";
 import { installSecretEnvScrubRecorder } from "./observability/secret-env-scrub.js";
+import { buildDisplaySafeUrl } from "./trace/redact.js";
 export function parseArgs(argv) {
     let objective;
     let root;
@@ -299,7 +300,7 @@ export async function runLocal(argv, deps = {}) {
             ...(config.memorySync.maxPushEntries !== undefined ? { maxPushEntries: config.memorySync.maxPushEntries } : {}),
             ...(config.memorySync.maxPullEntries !== undefined ? { maxPullEntries: config.memorySync.maxPullEntries } : {}),
         });
-        logger.info("memory_sync_enabled", { url: config.memorySync.url, scope: config.memorySync.scope, cursorPath: memorySync.cursorPath });
+        logger.info("memory_sync_enabled", { url: buildDisplaySafeUrl(config.memorySync.url), scope: config.memorySync.scope, cursorPath: memorySync.cursorPath });
         memorySync.trigger("boot");
     }
     else if (config.memorySync) {

package/dist/sealed-key.js

@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 import { chmod, mkdir, readdir, readFile, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import _sodium from "libsodium-wrappers";
+import { buildDisplaySafeUrl } from "./trace/redact.js";
 export const SEALED_KEY_ALG = "libsodium-sealedbox-x25519";
 const SEAL_OVERHEAD_BYTES = 48;
 const BASE64_STRICT = /^[A-Za-z0-9+/]+={0,2}$/;
@@ -104,7 +105,7 @@ export async function reportExecutionPublicKey(opts) {
             alg: SEALED_KEY_ALG,
             createdAt: key.createdAt,
             why,
-            register: `POST ${baseUrl ?? "<registry>"}/api/config/execution-keys (admin token) body {"publicKey":"${key.publicKey}","publicKeyId":"${key.publicKeyId}"}`,
+            register: `POST ${baseUrl === undefined ? "<registry>" : buildDisplaySafeUrl(baseUrl)}/api/config/execution-keys (admin token) body {"publicKey":"${key.publicKey}","publicKeyId":"${key.publicKeyId}"}`,
             note: "until an admin registers this public key, web-pasted (sealed) api keys cannot target this host",
         });
     };

package/dist/security.d.ts

@@ -185,6 +185,12 @@ export declare class HttpError extends Error {
         extra?: Record<string, unknown>;
     });
 }
+/**
+ * 带机读码的 {@link HttpError} 的**构造点**。出门时这只码落在 wire 错误体的 `errorCode` 键上(`http/send.ts`),
+ * 从不以裸 `code` 键出现 —— 3.0.0 起 `errorCode` 是错误体唯一的机器判别键。`http/` 树里的模块经它抛带码错误,
+ * 不手写 `{ code }` 选项字面量(那一层有一道按行扫裸 `code:` 键的门,手写字面量与「真发了 legacy 键」同形)。
+ */
+export declare function createCodedHttpError(status: number, errorCode: string, message: string, extra?: Record<string, unknown>): HttpError;
 /**
  * Authorization context resolved per request, BEFORE building the TaskSpec. The service owns this —
  * identity and tenant scope come from the authenticated channel, **never from the request body**.

package/dist/security.js

@@ -39,6 +39,9 @@ export class HttpError extends Error {
             this.extra = opts.extra;
     }
 }
+export function createCodedHttpError(status, errorCode, message, extra) {
+    return new HttpError(status, message, extra === undefined ? { code: errorCode } : { code: errorCode, extra });
+}
 export function createAuthorizer(config, sessionStore) {
     return async ({ req, body }) => {
         const principal = verifiedPrincipal(req, config);

package/dist/session-titler.js

@@ -1,5 +1,6 @@
 import { CONTROL_AND_BIDI_STRIP_RE } from "./text-bidi.js";
 import { recordFailOpen } from "./observability/fail-open.js";
+import { redactSecrets } from "./trace/redact.js";
 export const TITLE_MAX_CHARS = 80;
 const OBJECTIVE_SNIPPET_CHARS = 600;
 const LLM_TIMEOUT_MS = 15_000;
@@ -23,8 +24,9 @@ export function buildTitlePrompt(objective) {
 export function createSessionTitler(deps) {
     const seen = new Set();
     const logFailure = (sessionId, error) => {
-        deps.logger?.debug?.("session_title_failed", { sessionId, error: error.slice(0, 200) });
-        recordFailOpen("server.session-titler.gateway-unreachable", error.slice(0, FAIL_CAUSE_KEY_CHARS));
+        const safe = redactSecrets(error);
+        deps.logger?.debug?.("session_title_failed", { sessionId, error: safe.slice(0, 200) });
+        recordFailOpen("server.session-titler.gateway-unreachable", safe.slice(0, FAIL_CAUSE_KEY_CHARS));
     };
     const probeOrContinue = async (sessionId, continueWord) => deps
         .probeTitle(sessionId)