@sema-agent/server 7.119.0 → 7.121.0

package/dist/config.js

@@ -10,7 +10,10 @@ import { DEFAULT_ELICITATION_THROTTLE } from "./elicitation.js";
 import { isV2ScopeKey, memoryReplicationCoverage, replicationCovers } from "./memory-scope.js";
 import { DEFAULT_QUESTION_THROTTLE } from "./question.js";
 import { GIT_API_KINDS, isGitApiKind } from "./git-api-kind.js";
-import { CONFIG_PROVIDER_WORDS, RETENTION_MODES, MEMORY_CONSOLIDATION_MIN_INTERVAL_SEC, RESILIENCE_DEFAULTS, TASK_WRITE_FACE_ESCALATIONS, MAX_TIMER_DELAY_MS, AUTO_MODE_CLASSIFIER_TIMEOUT_BOUNDS, DRAIN_GRACE_FLOOR_MS, DRAIN_SECOND_SIGNAL_MIN_GAP_BOUNDS, DRAIN_SECOND_SIGNAL_MIN_GAP_DEFAULT_MS, FIRST_BYTE_TIMEOUT_BOUNDS } from "./config-types.js";
+import { CONFIG_PROVIDER_WORDS, RETENTION_MODES, MEMORY_CONSOLIDATION_MIN_INTERVAL_SEC, RESILIENCE_DEFAULTS, TASK_WRITE_FACE_ESCALATIONS, MAX_TIMER_DELAY_MS, AUTO_MODE_CLASSIFIER_TIMEOUT_BOUNDS, DRAIN_GRACE_FLOOR_MS, DRAIN_SECOND_SIGNAL_MIN_GAP_BOUNDS, DRAIN_SECOND_SIGNAL_MIN_GAP_DEFAULT_MS, FIRST_BYTE_TIMEOUT_BOUNDS, FLEET_LEASE_OUTAGE_MAX_DEFAULT_MS, fleetScopeOf } from "./config-types.js";
+import { FLEET_GENERATION_ENV, FLEET_SCOPE_ENV, SERVING_LEASE_TTL_FLOOR_MS, isCanonicalGeneration } from "@sema-agent/settings-schema/fleet";
+import { ScopeId } from "@sema-agent/settings-schema/api/scopes";
+import { centerLaneConfigured, pathBaseUrlFlaw } from "./config-center/center-request.js";
 import { resolveLocalDataRoot } from "./local-data-root.js";
 import { buildWriteProtectionPosture } from "./write-protection.js";
 import { normalizeSshFingerprint } from "./ssh-host-key.js";
@@ -20,6 +23,8 @@ import {} from "./posture-source.js";
 import { CONTROL_AND_BIDI_STRIP_RE } from "./text-bidi.js";
 import { describeUnmatchableRuleName, ruleEntryToolName, unmatchableRuleNameOf } from "./namespaced-rule-name.js";
 import { bakeOperatorPrincipalsRefusal, bakeRunnerCredentialRefusal, halfOpenDirectDoorRefusal, leaderDurableStoreRefusal, operatorPrincipalsRequiredRefusal } from "./config-invariants.js";
+import { declaredSemaConfigDir } from "./sema-config-dir.js";
+import { lkgPathOverrideOf } from "./config-lkg.js";
 import { REMOTE_EXEC_PROVIDER_WORDS, executionLaneOf, executionLaneRequiredRefusal, isSingleMachineDefaultLane, laneRequiredEnv } from "./execution-lane-caps.js";
 import { MEMORY_ENGINE_BACKENDS, SESSION_BACKENDS, STORE_BACKENDS } from "@sema-agent/settings-schema/execution-lanes";
 import { AUTONOMY_MODES } from "./runtime-governance.js";
@@ -29,6 +34,7 @@ import { parseCenterCredentialRenewLeadMs } from "./center-credential-renewer.js
 import { modelProviderRefusal } from "./model-provider.js";
 import { modelRouteUrlRefusal } from "./model-route-url.js";
 import { modelRouteEndpointRefusal } from "./model-route-endpoint.js";
+import { displayListEntry } from "./list-entry-display.js";
 import { buildDisplaySafeUrl, redactSecrets } from "./trace/redact.js";
 import { allowlistedEnv } from "./server-secret-env.js";
 import { ENV_NAME_ALLOWLIST_KNOBS, ENV_NAME_ALLOWLIST_KNOB_NAMES, describeAllowlistPostures } from "./env-name-allowlist-knobs.js";
@@ -485,7 +491,6 @@ function boolEnv(name, def) {
     registerKnob({ name, polarity: def ? "opt-out" : "opt-in", value, source });
     return value;
 }
-export const configLkgEnabled = () => boolEnv("CONFIG_LKG_ENABLED", true);
 export const hostBackgroundShellEnabled = () => boolEnv("HOST_BG_ENABLED", true);
 export const hostExecSpoolEnabled = () => boolEnv("HOST_EXEC_SPOOL_ENABLED", true);
 function parseReadDenyPatternsEnv(raw) {
@@ -1209,17 +1214,11 @@ function parseDegradeOn(words) {
     }
     return words;
 }
-const PRESENTED_NAME_MAX = 160;
-function presentToolName(name) {
-    const clean = name.replace(CONTROL_AND_BIDI_STRIP_RE, "");
-    return clean.length <= PRESENTED_NAME_MAX ? clean : `${clean.slice(0, PRESENTED_NAME_MAX)}…(${name.length} chars)`;
-}
 function ccRuleFormGuidance(name) {
     if (!name.includes("(") && !name.includes(")"))
         return undefined;
-    const shown = presentToolName(name);
-    return (`CC-form rule specifier — this list matches the WHOLE tool name verbatim, so it can only ever match a tool literally named "${shown}". ` +
-        `Drop the parentheses to gate the tool itself ("${presentToolName(name.split("(")[0] ?? name)}"); ` +
+    return (`CC-form rule specifier — this list matches the WHOLE tool name verbatim, so it can only ever match a tool literally named ${displayListEntry(name)}. ` +
+        `Drop the parentheses to gate the tool itself (${displayListEntry(name.split("(")[0] ?? name)}); ` +
         `to decide per COMMAND use \`runtime.commandPolicy\` ({command, decision} — bare argv[0] names); ` +
         `to put every shell call behind an approval use MANUAL_MODE_SHELL_GATE=always`);
 }
@@ -1264,7 +1263,7 @@ export function unmatchableToolNamesRefusal(source, names, judgment) {
         return undefined;
     const message = (`${source} has ${bad.length === 1 ? "an entry" : "entries"} that can never take effect — ${bad.length === 1 ? "it" : "each"} would never match a live tool or cannot be compiled into a rule ` +
         `(names are read exactly as written: no alias folding, no protocol prefix added): ` +
-        bad.map((b) => `${presentToolName(b.name)} → ${b.guidance}`).join("; ")).replace(CONTROL_AND_BIDI_STRIP_RE, "");
+        bad.map((b) => `${displayListEntry(b.name)} → ${b.guidance}`).join("; ")).replace(CONTROL_AND_BIDI_STRIP_RE, "");
     return { message, names: bad.map((b) => b.name) };
 }
 const APPROVAL_GRANT_ENV = "APPROVAL_GRANT";
@@ -1856,7 +1855,6 @@ function parseOrchestrationDomain(ctx) {
     const workflowSizeGuideline = workflowSizeGuidelineRaw;
     const usageWindows = parseUsageWindows(process.env.USAGE_WINDOWS);
     const bakeRunnerPrincipal = env("BAKE_RUNNER_PRINCIPAL", "system:bake-runner");
-    configLkgEnabled();
     hostBackgroundShellEnabled();
     hostExecSpoolEnabled();
     const lspHostEnabled = (() => {
@@ -1899,6 +1897,9 @@ function parseOrchestrationDomain(ctx) {
             assertReadDenyBuiltinsResolvable(tiers, exclude);
             return { ...(tiers !== undefined ? { readDenyBuiltinTiers: tiers } : {}), ...(exclude !== undefined ? { readDenyBuiltinExclude: exclude } : {}) };
         })(),
+        ...((dir) => (dir !== undefined ? { agentConfigDir: dir } : {}))(declaredSemaConfigDir()),
+        ...((p) => (p !== undefined ? { configLkgPath: p } : {}))(lkgPathOverrideOf(process.env.CONFIG_LKG_PATH)),
+        configLkgEnabled: boolEnv("CONFIG_LKG_ENABLED", true),
         ...((h) => (h !== undefined ? { remoteExecHomeDir: h } : {}))((() => {
             const raw = process.env.REMOTE_EXEC_HOME_DIR;
             if (raw === undefined || raw === "")
@@ -2187,6 +2188,13 @@ function parseGitApiKind(raw, baseUrl) {
 }
 function parseIntegrationsDomain(ctx) {
     const { requirePrincipal, configProvider } = ctx;
+    const registryUrl = parseCenterBaseUrl("SEMA_REGISTRY_URL", process.env.SEMA_REGISTRY_URL, `It is the center base every config pull, fleet and lease request is sent to; setting it selects the center as the config source.`);
+    const registryLiveUrl = parseCenterBaseUrl("SEMA_REGISTRY_LIVE_URL", process.env.SEMA_REGISTRY_LIVE_URL, `It is the center base the fleet liveness endpoints (heartbeat, serving lease) are sent to; unset it to send them to SEMA_REGISTRY_URL.`);
+    const registryWebUrl = parseCenterBaseUrl("SEMA_REGISTRY_WEB_URL", process.env.SEMA_REGISTRY_WEB_URL, `It is the center's web console base this engine reports on GET /health (center.webBaseUrl); unset it if the center has no web console to link to.`);
+    const configCenter = registryUrl !== undefined ? parseConfigCenter(registryUrl, requirePrincipal, registryLiveUrl, registryWebUrl) : undefined;
+    const fleetGeneration = parseFleetGeneration(process.env.FLEET_GENERATION);
+    const fleetAdvertiseAddress = parseFleetAdvertiseAddress(process.env.FLEET_ADVERTISE_ADDRESS);
+    fleetFenceLaneOf({ ...fleetGeneration, configCenter, ...fleetAdvertiseAddress });
     return {
         pluginsAllowHosts: (process.env.PLUGINS_ALLOW_HOSTS ?? "github.com").split(",").map((h) => h.trim()).filter(Boolean),
         configBootFetchBudgetMs: clampEnvWithWarn("CONFIG_BOOT_FETCH_BUDGET_MS", "1500", 0),
@@ -2196,24 +2204,107 @@ function parseIntegrationsDomain(ctx) {
         defaultScenario: env("DEFAULT_SCENARIO", "code"),
         skillsDir: env("SKILLS_DIR", defaultSkillsDir()),
         centerCredentialRenewLeadMs: parseCenterCredentialRenewLeadMs(process.env.CENTER_CREDENTIAL_RENEW_LEAD_MS),
-        configCenter: process.env.SEMA_REGISTRY_URL ? parseConfigCenter(env("SEMA_REGISTRY_URL"), requirePrincipal) : undefined,
+        configCenter,
         fleetLeaseFailClosed: parseFleetLeaseFailClosed(process.env.FLEET_LEASE_FAIL_CLOSED, requirePrincipal),
+        ...fleetGeneration,
+        fleetScope: parseFleetScope(process.env.FLEET_SCOPE),
+        ...fleetAdvertiseAddress,
+        fleetLeaseOutageMaxMs: parseFleetLeaseOutageMaxMs(process.env.FLEET_LEASE_OUTAGE_MAX_MS),
         ...(configProvider !== undefined ? { configProvider } : {}),
         configLocalDir: process.env.CONFIG_LOCAL_DIR || undefined,
         a2aServe: parseA2aServe(),
     };
 }
+function parseFleetGeneration(raw) {
+    const name = "FLEET_GENERATION";
+    if (raw === undefined)
+        return {};
+    const shown = raw.length > 40 ? `${raw.slice(0, 40)}…(${raw.length} chars)` : raw;
+    if (!isCanonicalGeneration(raw)) {
+        throw fleetEnvRefusal("generation_invalid", `env ${name}=${JSON.stringify(shown)} is not a generation: it must be a canonical non-negative decimal string ("0", "7", "10" — no leading zero, ` +
+            `sign, whitespace or fraction, and not empty). The config renderer sets it on fleet members; unset it entirely for a standalone engine. ` +
+            `Refusing to boot rather than running outside the serving-lease fence.`);
+    }
+    return { fleetGeneration: raw };
+}
+export const FLEET_ENV_REFUSAL_CODES = {
+    generation_invalid: "config.fleet_generation_invalid",
+    scope_invalid: "config.fleet_scope_invalid",
+    advertise_address_invalid: "config.fleet_advertise_address_invalid",
+    member_unfenced: "config.fleet_member_unfenced",
+};
+function fleetEnvRefusal(rule, message) {
+    return Object.assign(new Error(message), { code: FLEET_ENV_REFUSAL_CODES[rule] });
+}
+function parseFleetScope(raw) {
+    const name = "FLEET_SCOPE";
+    if (raw !== undefined && !ScopeId.safeParse(raw).success) {
+        const shown = raw.length > 40 ? `${raw.slice(0, 40)}…(${raw.length} chars)` : raw;
+        throw fleetEnvRefusal("scope_invalid", `env ${name}=${JSON.stringify(shown)} is not a scope id: it must be a lowercase slug of letters, digits and inner dashes, 1–64 characters, ` +
+            `not empty. The config renderer sets it on engines that serve a tenant scope; unset it for the default scope ("${fleetScopeOf(undefined)}"). ` +
+            `Refusing to boot rather than answering drain requests under the wrong identity.`);
+    }
+    return fleetScopeOf(raw);
+}
+function parseFleetAdvertiseAddress(raw) {
+    if (raw === undefined || raw === "")
+        return {};
+    const why = pathBaseUrlFlaw(raw);
+    if (why !== undefined) {
+        throw fleetEnvRefusal("advertise_address_invalid", `env FLEET_ADVERTISE_ADDRESS ${why} (an http(s) base URL, e.g. "http://10.0.0.5:8090"); got ${JSON.stringify(buildDisplaySafeUrl(raw))} — ` +
+            `the fleet center rejects any other shape on every announce. Unset it if this engine does not announce itself.`);
+    }
+    return { fleetAdvertiseAddress: raw };
+}
+export function fleetFenceLaneOf(cfg) {
+    const generation = cfg.fleetGeneration;
+    if (generation === undefined)
+        return undefined;
+    const laneConfigured = centerLaneConfigured(cfg);
+    if (laneConfigured && cfg.fleetAdvertiseAddress !== undefined)
+        return { center: cfg.configCenter, generation };
+    const missing = [
+        ...(laneConfigured ? [] : [`the center lane (SEMA_REGISTRY_URL + ${CENTER_CREDENTIAL_ENV.token} or ${CENTER_CREDENTIAL_ENV.tokenFile} + SEMA_REGISTRY_WORKER)`]),
+        ...(cfg.fleetAdvertiseAddress === undefined ? ["the announce address (FLEET_ADVERTISE_ADDRESS)"] : []),
+    ];
+    throw fleetEnvRefusal("member_unfenced", `fleet member cannot be fenced — env FLEET_GENERATION=${JSON.stringify(generation)} makes this engine a fleet member, ` +
+        `but ${missing.join(" and ")} ${missing.length === 1 ? "is" : "are"} not configured. A member renews its serving lease with the center and hears whether ` +
+        `the center enforces the lease only in the heartbeat reply (the heartbeat needs the announce address); without them it would serve outside the fence. ` +
+        `Configure them, or unset FLEET_GENERATION for a standalone engine.`);
+}
+function parseFleetLeaseOutageMaxMs(raw) {
+    if (raw === undefined || raw === "")
+        return FLEET_LEASE_OUTAGE_MAX_DEFAULT_MS;
+    const n = /^(0|[1-9]\d*)$/.test(raw) ? Number(raw) : Number.NaN;
+    if (!Number.isSafeInteger(n) || n < SERVING_LEASE_TTL_FLOOR_MS) {
+        const shown = raw.length > 40 ? `${raw.slice(0, 40)}…(${raw.length} chars)` : raw;
+        throw new Error(`env FLEET_LEASE_OUTAGE_MAX_MS=${JSON.stringify(shown)} must be a whole number of milliseconds ≥ ${SERVING_LEASE_TTL_FLOOR_MS} (the serving-lease TTL floor; ` +
+            `decimal digits only; unset = ${FLEET_LEASE_OUTAGE_MAX_DEFAULT_MS}, 24 h). It bounds how long this engine keeps taking new submissions after its serving ` +
+            `lease expired with the center unreachable — "0" and "infinite" are not values (the tolerance must be bounded and non-trivial). Refusing to boot.`);
+    }
+    return n;
+}
 function parseFleetLeaseFailClosed(raw, requirePrincipal) {
     const explicit = parseBoolWord("FLEET_LEASE_FAIL_CLOSED", raw);
     const value = explicit ?? requirePrincipal;
     registerKnob({ name: "FLEET_LEASE_FAIL_CLOSED", polarity: "posture", value, source: explicit !== undefined ? "env" : requirePrincipal ? "posture" : "default" });
     return value;
 }
-function parseConfigCenter(baseUrl, requirePrincipal) {
+function parseCenterBaseUrl(name, raw, role) {
+    if (raw === undefined || raw === "")
+        return undefined;
+    const why = pathBaseUrlFlaw(raw);
+    if (why !== undefined)
+        throw new Error(`env ${name} ${why}; got ${JSON.stringify(buildDisplaySafeUrl(raw))}. ${role}`);
+    return raw;
+}
+function parseConfigCenter(baseUrl, requirePrincipal, liveBaseUrl, webBaseUrl) {
     const worker = process.env.SEMA_REGISTRY_WORKER || undefined;
     const declared = readCenterCredentialDeclaration();
     return {
         baseUrl,
+        ...(liveBaseUrl !== undefined ? { liveBaseUrl } : {}),
+        ...(webBaseUrl !== undefined ? { webBaseUrl } : {}),
         credential: createCenterCredentialSource(declared.from === "file" ? { ...declared, multiTenant: requirePrincipal } : declared, worker),
         dryRun: boolEnv("SEMA_REGISTRY_DRY_RUN", false),
         worker,
@@ -2337,6 +2428,7 @@ const ORCHESTRATION_GROUP_KEYS = [
     "backgroundAgentParkClaimStaleMs", "delegationEntryCaps", "rosterRetentionMs", "leaderRunStaleMs", "scratchpadSweepTtlMs", "sandboxPkgSource",
     "sessionAutoTitle", "sessionAutoTitleSource", "selectEnvironmentTool", "envFactsEnabled", "toolDeferLongtail", "lspEnabled", "lspHostEnabled", "lspEnvAllow",
     "imageBakes", "readFace", "readFaceSource", "taskWriteFaceEscalation", "readDenyPatterns", "readDenyBuiltinTiers", "readDenyBuiltinExclude",
+    "agentConfigDir", "configLkgPath", "configLkgEnabled",
 ];
 const LIMITS_HTTP_GROUP_KEYS = [
     "port", "attachmentOrphanGraceMs", "workspaceFileMaxBytes", "attachmentMaxBytes", "attachmentMimeAllowlist",
@@ -2348,7 +2440,7 @@ const LIMITS_HTTP_GROUP_KEYS = [
 const OBSERVABILITY_GROUP_KEYS = ["metricsToken", "traceToken", "toolTrace", "traceThinking", "logLevel", "otel"];
 const INTEGRATIONS_GROUP_KEYS = [
     "pluginsAllowHosts", "mcpServers", "a2aPeers", "a2aServe", "configBootFetchBudgetMs", "gitApiBaseUrl", "gitApiToken", "gitApiKind", "defaultScenario",
-    "skillsDir", "centerCredentialRenewLeadMs", "configCenter", "fleetLeaseFailClosed", "configProvider", "configLocalDir",
+    "skillsDir", "centerCredentialRenewLeadMs", "configCenter", "fleetLeaseFailClosed", "fleetGeneration", "fleetScope", "fleetAdvertiseAddress", "fleetLeaseOutageMaxMs", "configProvider", "configLocalDir",
 ];
 export const CONFIG_GROUP_KEYS = {
     store: STORE_GROUP_KEYS,

package/dist/deployment-governance.d.ts

@@ -11,6 +11,8 @@ export interface DeploymentGovernanceConfigView {
     readonly commandPolicy?: ServiceConfig["commandPolicy"];
     readonly manualModeShellGate?: ServiceConfig["manualModeShellGate"];
     readonly sensitiveWritePatterns: ServiceConfig["sensitiveWritePatterns"];
+    /** core 7.46.0 #1419:部署声明的配置根 —— 守卫集的 `.sema/…` 模式在根下同样守(与 Runner 的同名座同一个值,`loadConfig` 铸)。 */
+    readonly agentConfigDir?: ServiceConfig["agentConfigDir"];
     /**
      * 本部署的**本地店根**(`LOCAL_DATA_ROOT → CONFIG_LOCAL_DIR → AGENT_DATA_DIR → ~/.ai-agent`)—— 在本口只喂
      * **誊本门**(`<localDataRoot>/sessions`)。S-133 起它**不再**当守卫集的 `dataRoot`(那是引擎记忆根,见
@@ -185,7 +187,7 @@ type WriteTargetForm = "unstamped-relative" | "absolute-or-stamped";
  *  · `writeTargetGuard`(守卫集策略自带,shell 写站问「这个绝对目标守不守」)—— 只在本层的形**覆盖守卫的入参形**时带上
  *    ({@link WRITE_TARGET_GUARD_DOMAIN}):真身层带;词法层不带(它的 env 对绝对形报错 ⇒ core 的「判不了就守」会把每一次
  *    shell 写都判成受守,正与两层射程互补的原设计相反)。这不是给某一形开的特例,是同一条「成员描述它守得住的那部分」的读法;
- *  · `projection` / `pathDenyRules` / `nameSets` —— 守卫集策略不带,本包装也不报(报了就是替它声称一张它没有的拒表)。
+ *  · `projection` / `pathRules` / `nameSets` —— 守卫集策略不带,本包装也不报(报了就是替它声称一张它没有的拒表)。
  * 修前(core 7.33.x)这里是一只 `{ check }` 字面量,7.34.0 起那只字面量把真身层的守卫剥掉了 —— 沙箱 lane 的 shell 写站
  * 因此看不见部署守卫集(`cp x .env` 在 acceptEdits 下被引擎 place 并答掉)。
  */

package/dist/deployment-governance.js

@@ -87,18 +87,20 @@ export function createDeploymentGovernanceInputs(config, pathAdjudication, roots
     const sensitivePathLayers = config.sensitiveWritePatterns.length > 0
         ? (() => {
             const dataRootOpt = roots.engineDataRoot !== undefined ? { dataRoot: roots.engineDataRoot } : {};
+            const configRootOpt = config.agentConfigDir !== undefined ? { agentConfigDir: config.agentConfigDir } : {};
             const realTarget = createSensitivePathPolicy({
                 env: pathAdjudication.env,
                 patterns: config.sensitiveWritePatterns,
                 ...(pathAdjudication.cwd !== undefined ? { rootPath: pathAdjudication.cwd } : {}),
                 ...dataRootOpt,
+                ...configRootOpt,
             });
             const transcriptGuard = config.localDataRoot !== undefined ? [createTranscriptIntegrityPolicy({ sessionsDirs: [join(config.localDataRoot, "sessions")] })] : [];
             if (pathAdjudication.cwd !== undefined)
                 return [realTarget, ...transcriptGuard];
             return [
                 scopedToWriteTargetForm(realTarget, "absolute-or-stamped"),
-                scopedToWriteTargetForm(createSensitivePathPolicy({ env: new RelativeTargetLexicalEnv(), patterns: config.sensitiveWritePatterns, ...dataRootOpt }), "unstamped-relative"),
+                scopedToWriteTargetForm(createSensitivePathPolicy({ env: new RelativeTargetLexicalEnv(), patterns: config.sensitiveWritePatterns, ...dataRootOpt, ...configRootOpt }), "unstamped-relative"),
                 ...transcriptGuard,
             ];
         })()

package/dist/device-store.d.ts

@@ -161,6 +161,13 @@ export declare const DEVICE_TEXT_LIMITS: {
     readonly connEpoch: 64;
     readonly replicaId: 128;
 };
+/**
+ * 设备侧路径「是不是绝对路径」的**唯一判据**(v1 设备都是 POSIX:`platformOs` 闭集 `darwin` | `linux`;用 `posix` 而不是 `node:path`,
+ * server 跑在什么平台上与设备路径语义无关)。两处读它、不写第二份:入籍口(`http/routes/devices.ts`,`workspaceRoot` 不过 ⇒ 400)与
+ * 铸 env(`plugins/remote-env-device.ts` `effectiveDeviceCwd`,有效工作目录不过 ⇒ 响亮拒;那一道守的是入籍口收紧之前落库的存量行与
+ * 会话 / 委派链来的 cwd)。
+ */
+export declare function isDeviceAbsolutePath(p: string): boolean;
 export declare function assertDeviceOwnerShape(owner: DeviceOwner): void;
 export declare function assertDeviceIdShape(deviceId: string): void;
 export declare function assertRootSessionIdShape(rootSessionId: string): void;

package/dist/device-store.js

@@ -1,4 +1,5 @@
 import { createHash, randomBytes, randomInt } from "node:crypto";
+import { posix } from "node:path";
 export const DEVICE_ERROR_CODES = {
     NOT_BOUND: "device.not_bound",
     OFFLINE: "device.offline",
@@ -86,6 +87,9 @@ export const DEVICE_TEXT_LIMITS = {
     connEpoch: 64,
     replicaId: 128,
 };
+export function isDeviceAbsolutePath(p) {
+    return posix.isAbsolute(p);
+}
 export function assertDeviceOwnerShape(owner) {
     assertIdentityKey("owner.tenant", owner.tenant, DEVICE_KEY_MAX_BYTES);
     assertIdentityKey("owner.subject", owner.subject, DEVICE_KEY_MAX_BYTES);

package/dist/device-ws-hub.js

@@ -425,7 +425,20 @@ export function createDeviceWsHub(options) {
             clearTimeout(conn.handshakeTimer);
         conn.handshakeTimer = null;
         releasePreAuthSlot(conn);
-        sendServerFrame(conn, { t: "helloAck", ok: true, heartbeatIntervalMs, maxInflight: maxInflightPerDevice, gen: conn.genStr, pendingInstructions: pendingIds, chunkWatermarks });
+        const helloAck = {
+            t: "helloAck",
+            ok: true,
+            heartbeatIntervalMs,
+            maxInflight: maxInflightPerDevice,
+            gen: conn.genStr,
+            pendingInstructions: pendingIds,
+            chunkWatermarks,
+            reconnectGraceMs,
+            cancelGraceMs,
+            chunkGapTimeoutMs,
+            executionCeilingGraceMs: execGraceMs,
+        };
+        sendServerFrame(conn, helloAck);
         logger?.info?.("device_connected", { deviceId: row.deviceId, generation: acquired.generation, epoch: frame.epoch, replicaId });
         metrics?.inc("device_connected_total");
     }
@@ -469,12 +482,7 @@ export function createDeviceWsHub(options) {
         }
     }
     function failOnChunkGap(p) {
-        const missing = p.nextStreamSeq;
-        settle(p, {
-            ok: false,
-            errorCode: "outcome_unknown",
-            message: `the output stream had a gap (missing chunk streamSeq ${missing}) so the result cannot be reported faithfully — ${OUTCOME_UNKNOWN_SENTENCE}`,
-        });
+        settle(p, outcomeUnknown(`the output stream had a gap (missing chunk streamSeq ${p.nextStreamSeq}) so the result cannot be reported faithfully`));
     }
     function chunkPayloadBytes(frame) {
         return frame.dataB64 === undefined ? 0 : Math.floor((frame.dataB64.length * 3) / 4);
@@ -549,11 +557,11 @@ export function createDeviceWsHub(options) {
         if (complaint !== null) {
             metrics?.inc("device_stream_terminator_missing_total");
             sendServerFrame(conn, { t: "resultAck", gen: conn.genStr, instructionId: p.instructionId });
-            settle(p, { ok: false, errorCode: "outcome_unknown", message: `${complaint} — ${OUTCOME_UNKNOWN_SENTENCE}` });
+            settle(p, outcomeUnknown(complaint));
             return;
         }
         sendServerFrame(conn, { t: "resultAck", gen: conn.genStr, instructionId: p.instructionId });
-        settle(p, outcome);
+        settle(p, !outcome.ok && outcome.errorCode === "outcome_unknown" ? outcomeUnknown(outcome.message) : outcome);
     }
     function onDeviceText(conn, text) {
         conn.lastFrameAt = Date.now();

package/dist/device-ws-protocol.d.ts

@@ -235,6 +235,21 @@ export type DeviceHelloAckFrame = {
     gen: string;
     pendingInstructions: string[];
     chunkWatermarks: Record<string, number>;
+    /**
+     * 四个**宽限位**(additive,协议 §5.6 不升版):本连接所在 server 副本**此刻生效**的四只预算,值与汇聚端
+     * 计时器读的是同一只常量 —— 不是文档里的「默认值」,是这台部署的实际值。executor 据此定自己的重连
+     * 退避上界 / 取消应答时限 / 补片节奏 / 执行兜底预算,不必抄文档里的数。
+     *  · `reconnectGraceMs`:断连后在途不判丢的窗(R4;运维旋钮 `DEVICE_RECONNECT_GRACE_MS`);
+     *  · `cancelGraceMs`:`cancel` 送达后等终局回执的窗(R11);
+     *  · `chunkGapTimeoutMs`:等缺失 `streamSeq` 的上限(R8);
+     *  · `executionCeilingGraceMs`:`timeoutMs` 之后云侧兜底再等的宽限(R12:`timeoutMs` + 本值)。
+     * **可选位**:7.120+ 服务端恒发;缺席 = 老服务端,按协议 §1.5 回落文档缺省(不得当 0)。型上标可选,是为了让拿这只型读老服务端帧的
+     * 消费方被编译器逼着处理缺席;本服务自己的铸点按 `Required<DeviceHelloAckFrame>` 构造(`device-ws-hub.ts`),漏一位编译红。
+     */
+    reconnectGraceMs?: number;
+    cancelGraceMs?: number;
+    chunkGapTimeoutMs?: number;
+    executionCeilingGraceMs?: number;
 };
 export type DeviceHelloRejectFrame = {
     t: "helloReject";

package/dist/fleet/drain-entry.d.ts

@@ -0,0 +1,87 @@
+/**
+ * 排空的**一只入口**(编排器长远稿片 2 件 2;契约型 = settings-schema 8.1.0 `DrainRequest` / `DrainReceipt` / `EngineDraining`)。
+ *
+ * ## 规则
+ *
+ *  1. **一只入口,两条车道**:进入排空只有 `boot/shutdown.ts` 的 `enterDrain`(装在 {@link DrainState.enter} 上)一处。Docker 车道 / 中心直调
+ *     经 `POST /v1/admin/drain`(体 = `DrainRequest`);Kubernetes 车道经服务租约被拒(`fleet/serving-lease.ts`,`actionId = lease:<代际>`);
+ *     非编排路径 = 停止信号(SIGTERM)/ SIGHUP 升级 / 附着租约自退,动作号由引擎自铸({@link ENGINE_DRAIN_CAUSES})。全部汇到同一只入口。
+ *  2. **期限在进入那一拍定死**:请求带的 `deadlineAt` 原样;引擎自起的排空 = 起点 + 此刻的排空窗(`drainGraceMs`)。之后改窗(中心热改
+ *     `limits.drainGraceMs`)不动在跑的期限 —— 排空驱动读的是期限,不是窗。
+ *  3. **幂等**:已在排空 ⇒ 不重置,回执 `already_draining` 带**第一次**的动作 / 起点 / 期限(不论这次的动作号是否相同)。
+ *  4. **身份**:逐字段比,任一不符 ⇒ 409 `conflict.fleet_identity`,零状态变化。
+ *     · `scope`:两侧都经 {@link fleetScopeOf} 读成值(缺席 = settings-schema 的缺省 scope,线上任何一处缺席的 scope 都读成它)再严格相等。
+ *       引擎这一侧的唯一来源 = env `FLEET_SCOPE`(`config.fleetScope`,`config.ts` 解析一次);请求不带 `scope` = 点名缺省 scope。
+ *     · `worker` / `expectedGeneration`:缺席对缺席(非 fleet 成员没有代际,不带 `expectedGeneration` 的请求是单机形,不是通配)。
+ *     · `instanceId`:请求带了才比(它是引擎每进程自铸的身份,`/health` 上可读);「点名的是不是别的进程」与 run 行同一只判据
+ *       `runProvenElsewhere`。
+ *     引擎自己的 worker / instanceId 读不出 ⇒ 带了这一项的请求不符(认不出自己就不认任何点名;没配 `SEMA_REGISTRY_WORKER` 的引擎因此
+ *     只能用停止信号排空)。
+ *  5. **进入那一拍让出在飞**:本副本可抢占的在飞腿经 core `TaskSpec.preemptSignal` 让出(在下一个干净的回合边界耐久停驻,
+ *     `resource_limit` / `preempt`;不合格的腿上 core 静默不动,等到期限硬停 —— 既有 `crashed` 臂);活的审批卡按断连同路改路耐久停驻
+ *     (协调器 `beginDrain`,core `onAsk` 答 `"unavailable"` 的合同);排空期间新登记的可抢占腿在登记那一拍让出(同一条规则)。
+ *
+ * 纯类型 + 纯函数叶(值 import 只有 scope 读法叶与 run 行判词叶)。
+ */
+import type { DrainReceipt, DrainRequest, EngineDraining } from "@sema-agent/settings-schema/fleet";
+/**
+ * 引擎自铸的动作号 —— **一张表**(排空事实与回执里不来自请求体的全部拼法;请求体的 `actionId` 由调用方自取):
+ *  · {@link ENGINE_DRAIN_CAUSES}:没有请求承载的排空成因(停止信号 / SIGHUP 升级 / 附着租约自退);
+ *  · {@link HARD_STOP_ACTION_ID}:硬停(未经排空)已在进行时排空口回执里的动作号 —— 不是一种排空成因,只说「这只进程已经在停,而且比你要的更快」;
+ *  · `lease:<代际>`:服务租约被拒的排空({@link leaseDrainActionId},每代一只:同一代被拒两次是同一个动作)。
+ * 按成因穷举的地方({@link DRAIN_CAUSE_COUNTS_AS_FIRST_STOP_SIGNAL})加一种成因不补格 = 编译红。
+ */
+export declare const ENGINE_DRAIN_CAUSES: readonly ["signal:SIGTERM", "signal:SIGHUP", "self-exit:attachment"];
+export type EngineDrainCause = (typeof ENGINE_DRAIN_CAUSES)[number];
+export declare const HARD_STOP_ACTION_ID = "hard-stop";
+export type LeaseDrainActionId = `lease:${string}`;
+/** 服务租约被拒时的动作号(每代一只)。 */
+export declare function leaseDrainActionId(generation: string): LeaseDrainActionId;
+/**
+ * 每种排空成因的**入口那一拍算不算本次排空的第一发停止信号**(`boot/shutdown.ts` 的「第二发 = 硬停」读它;它答的不是「这是不是 `StopSignal`」——
+ * `shutdown.ts` 的 `StopSignal` 闭集只有 SIGTERM / SIGINT,那是「哪些信号走停止处理器」)。算 ⇒ 之后隔 ≥ 最小间隔的一发即硬停;不算 ⇒ 期限由入口定死,
+ * 之后到达的第一发停止信号只被吸收(不缩短期限)。SIGHUP 算:SIGHUP 升级成排空要的就是**第二发** SIGHUP(第一发只开空闲窗),那是人 / 宿主又发了一次
+ * 停的意图,与 SIGTERM 进的排空同一个读法(7.120.0 起的行为)。闭集 Record。
+ */
+export declare const DRAIN_CAUSE_COUNTS_AS_FIRST_STOP_SIGNAL: {
+    readonly [C in EngineDrainCause]: boolean;
+};
+/** 入口的入参:动作号 + 期限(epoch ms)。 */
+export interface DrainEntry {
+    readonly actionId: string;
+    readonly deadlineAt: number;
+}
+/**
+ * 引擎与 HTTP 面共享的排空盒子(装配层建一只,`createHttpServer` 与收尾链各自往上装读口 / 入口)。
+ *  · `draining` / `since` / `actionId` / `deadlineAt` —— **只由** {@link enter} 整组写入(排空事实 = 契约 `EngineDraining`);
+ *  · `enter` —— 唯一入口(收尾链装;缺席 = 这个进程没有收尾链,如嵌入宿主 / 测试夹具);
+ *  · `yieldInflight` —— 让出本副本在飞的可抢占腿(`createHttpServer` 装);
+ *  · 其余四只是既有的读口(在飞数 / 活性时钟 / 附着流),语义见 `http/server.ts`。
+ */
+export interface DrainState {
+    draining: boolean;
+    since?: number;
+    actionId?: string;
+    deadlineAt?: number;
+    enter?: (entry: DrainEntry) => DrainReceipt;
+    yieldInflight?: () => void;
+    inflight?: () => number;
+    lastActivityAt?: () => number;
+    attachedStreams?: () => number;
+    lastAttachEndedAt?: () => number;
+}
+/** 排空盒子里的排空事实(三键齐才是;入口整组写,所以「缺一」只出现在手搭的夹具上)。 */
+export declare function drainingFactOf(s: Pick<DrainState, "draining" | "since" | "actionId" | "deadlineAt">): EngineDraining | undefined;
+/** 本进程的身份。`scope` 已读成值(`config.fleetScope`);其余三项与 `/health` 上读到的同一份。 */
+export interface EngineIdentity {
+    readonly scope: string;
+    readonly worker?: string;
+    readonly generation?: string;
+    readonly instanceId?: string;
+}
+/** 身份四元的字段名(请求侧拼法;409 拒句按它点名,不回显值)。 */
+export declare const DRAIN_IDENTITY_FIELDS: readonly ["scope", "worker", "expectedGeneration", "instanceId"];
+export type DrainIdentityField = (typeof DRAIN_IDENTITY_FIELDS)[number];
+/** 规则 4:不符的字段(按 {@link DRAIN_IDENTITY_FIELDS} 序;空 ⇔ 认得)。 */
+export declare function drainIdentityMismatches(req: Pick<DrainRequest, "scope" | "worker" | "expectedGeneration" | "instanceId">, self: EngineIdentity): DrainIdentityField[];
+//# sourceMappingURL=drain-entry.d.ts.map

package/dist/fleet/drain-entry.js

@@ -0,0 +1,35 @@
+import { fleetScopeOf } from "../config-types.js";
+import { runProvenElsewhere } from "../plugins/store-contracts.js";
+export const ENGINE_DRAIN_CAUSES = ["signal:SIGTERM", "signal:SIGHUP", "self-exit:attachment"];
+export const HARD_STOP_ACTION_ID = "hard-stop";
+export function leaseDrainActionId(generation) {
+    return `lease:${generation}`;
+}
+export const DRAIN_CAUSE_COUNTS_AS_FIRST_STOP_SIGNAL = {
+    "signal:SIGTERM": true,
+    "signal:SIGHUP": true,
+    "self-exit:attachment": false,
+};
+export function drainingFactOf(s) {
+    return s.draining && s.actionId !== undefined && s.since !== undefined && s.deadlineAt !== undefined ? { actionId: s.actionId, since: s.since, deadlineAt: s.deadlineAt } : undefined;
+}
+export const DRAIN_IDENTITY_FIELDS = ["scope", "worker", "expectedGeneration", "instanceId"];
+export function drainIdentityMismatches(req, self) {
+    return DRAIN_IDENTITY_FIELDS.filter((f) => {
+        switch (f) {
+            case "scope":
+                return fleetScopeOf(req.scope) !== self.scope;
+            case "worker":
+                return self.worker === undefined || req.worker !== self.worker;
+            case "expectedGeneration":
+                return req.expectedGeneration !== self.generation;
+            case "instanceId":
+                return req.instanceId !== undefined && (self.instanceId === undefined || runProvenElsewhere({ instanceId: req.instanceId }, self.instanceId));
+            default: {
+                const unhandled = f;
+                throw new Error(`drain identity: unknown field ${String(unhandled)}`);
+            }
+        }
+    });
+}
+//# sourceMappingURL=drain-entry.js.map