@sema-agent/server 7.119.0 → 7.120.0

package/MIGRATION.md

@@ -7,6 +7,60 @@
 > ⚠️ 完整清单在仓库根 `CHANGELOG.md`——它**不随 npm tarball 出包**(本文件随包)。看完整迁移窗的
 > 权威姿势是源码 tag diff:`git diff v<旧>..v<新>`(每版都推 `v<版本>` tag);npm 包页也镜像 CHANGELOG。
 
+## 7.120.0 —— 引擎 7.46.0:子代工具清单回到开跑前拒退役拼法、管到内建工具 · 配置根搬家后同护 · 回显条目一种渲染 · 路径规则锚在装入处
+
+**升级前核查(一句话)**:设了 `SEMA_CONFIG_DIR` 的部署确认那个目录能建出来、不是空串;`CONFIG_LKG_PATH` 不是空串;
+按 `agents[].denyTools` 拼错只告的调用方改正拼写。停驻中的委派子代不必为本版排空(第 5 条)。
+
+1. **勘误(7.119.0 节,已发节不改字节)**:7.119.0 节说 `/health` 多一键 `sessionBackend` —— 「多一键」错:`/health.sessionBackend` 是既有键(≤7.117.0 已在),
+   7.119.0 只把它与 `listening` 日志的读法收成一只、让 sema-up 的冒烟改读这一位。消费方按「已消费 / 不变」读,不要删读点。
+2. **子代 `agents[].denyTools` 的退役拼法(`bash`)与大小写孪生(`BASH`)回到开跑前拒**(`config.agent.unknown_tool`,句子点名现名 `Bash`;7.119.0 上只告不拒、子代照拿 `Bash`):
+   本服务的委派工具现在声明它逐次注入的工具名册,引擎列得出子代工具池。无人挂的名照旧只告不拒(运维日志 `runner_config_advisory`)。
+   `denyTools` / `allowTools` 现在管子代手里的**全部**工具 —— 委派池与内建 hands(`Read` / `Edit` / `Write` / `NotebookEdit` / `Bash` / `Grep` / `Glob` …):
+   `denyTools: ["Write"]` ⇒ 子代没有 `Write`;`allowTools` 只列调用方工具 ⇒ 子代一只内建工具都没有(要什么点名什么);内建只读子代(Explore / Plan)没有 `Edit` / `Write` / `NotebookEdit`。
+   hands 之外的引擎工具(`Monitor` 等)仍不受这两张表管;要按路径 / 命令拦而保留工具,写调用方权限策略的 deny 规则。
+3. **配置根搬家(`SEMA_CONFIG_DIR`)后,根下的配置文件与家目录下同护**:根下的 `settings.json` / `settings.local.json` / `engine-data/.env` / `config-lkg-*.json`
+   模型读不到(家目录 `~/.sema/` 下同名文件照旧读不到,两处都拒),写进根下要问一次。起服时建出那个目录(不在就建,权限 `0700`);建不出来或不是目录 ⇒
+   引擎拒启,拒句带码 `config.agent_config_dir_invalid`(建不出来时本服务先打一行 `sema_config_dir_unprovisioned`,点名旋钮与原因)。
+   **`SEMA_CONFIG_DIR=`(空串)**:≤7.119.x 空串 = 进程工作目录(LKG / skill 缓存 / scheduler 店落在那里);7.120.0 起空串**拒启** —— 去掉变量用 `~/.sema`,
+   或写出要的目录(要保持旧位置就写工作目录的路径)。
+   LKG 覆写到配置根外(`CONFIG_LKG_PATH`)⇒ 派生读拒行:写下的路径与经符号链接目录后真正落的路径各一行(拒句与内建行同一句)。行的射程按路径段串算 ——
+   去掉开头的 `/`、不锚到根:这串段在任意深度出现即拒、大小写不敏感(`CONFIG_LKG_PATH=/app/config-lkg.json` ⇒ 用户仓里的 `…/app/config-lkg.json`、
+   `…/APP/Config-LKG.json` 同样读不到,Grep 的结果里也不出现);引擎提供锚定单文件的读拒行之前如此,要少挡就把覆写路径写得更具体。`CONFIG_LKG_PATH=`(空串)拒启。
+   拒启行的形:带串码的异常印成 `<name> [<code>]: <message>`(按码匹配,不按句子)。
+   `AGENT_DATA_DIR` 搬到配置根之外的部署:引擎数据根下的 `.env` 不在这条规则的射程里 —— 用部署自己的读拒行(`READ_DENY_PATTERNS`)守它。
+4. **回显条目:人读句一种渲染,通告里的规则文本是原值**:拒句、起服拒启行里的工具名 / 规则条目一律是引擎的渲染 —— JSON 串形(带引号),看不见 / 印成空白的字符
+   写成 `\uXXXX`,超长截断;「can never take effect」拒句里的名字与「pre-prefix short form」指引里的建议名从不带引号变成带引号。
+   通告里的规则文本(`permission.allowed_tool_not_granted` 的 `detail.entries[].entry`、`permission.rule_row_dropped` 的 `detail.rows[].rule`)是条目的**脱敏原值**:
+   不加引号、不转义、本服务不另截断;认出的凭据换成脱敏记号,双向控制符 / 零宽字符等格式字符剥掉,C0 控制符保留(JSON 里写成转义)。7.119.0 的 `entry` 剥掉了
+   控制 / 双向符、超过 160 字截断并标原长 —— 把 `entry` 直接打到终端的消费方先自己中和控制符,或显示通告文本 `message`(那是渲染好的句子)。
+5. **停驻中的委派子代:本服务的续跑腿不触发引擎的「装入记录缺席」拒,升级前不必排空**:引擎 7.46.0 对宿主**重供**的父约束链查「每条规则装在哪条腿」的记录,
+   缺了且规则依赖装入腿(相对形、`/x` 形、`~/` 形)⇒ 拒 `resume.parent_constraint_mismatch`(`detail.reason: "installation_record_absent"`)。本服务 `/decide` 一只停驻子代时
+   重供的链只有部署段(审批名单、命令策略、敏感路径守卫集、誊本门、问答门),不带随腿锚定的路径规则,请求的 `settings.permissions` 规则不在链里 ⇒ 没有要拒的条目。
+   实测:7.119.0 停驻(父请求带 deny `Edit(src/**)` / ask `Edit(/src/**)` / deny `Read(~/secret/**)`)→ 7.120.0 `/decide` 三形都照常续跑完。
+   自建续跑腿、自己重供带这几形路径规则的父约束链的嵌入方不在此列(照引擎说明:让旧版 worker 做完,或过期后重提)。
+6. **请求规则的相对 / `/x` 形路径模式在沙箱 / 设备车道(与还没登记工作目录的 host 腿)上照收**(修前 422):引擎把规则锚在装入它的那条腿的真根;
+   相对模式**不随 `cd` 走**(`Read(a/b/**)` 在 `cd sub` 之后不再够到 `sub/a/b/…`;要任意层写 `**/a/b/**`)。
+7. **新通告码 `permission.rule_row_dropped`(上会话流)**:持久规则里有项目行的 scope root 不是完整绝对路径 ⇒ 那几行不参与本 run 的检查;`detail` 点名前八行(`rows[].rule` 与第 4 条同一只写法 = 规则文本的脱敏原值)。
+   这种行是 7.119.0 及更早的本服务入口收下的(`/v1/rules` 写口与两条导入面按「root 非空」收 `project:myproj`,当时引擎也收)。本版:
+   - **入口按引擎同一只谓词拒**(project root 必须是完整绝对路径 `/…`、`X:\…`、`\\host\…`):`POST` / `DELETE /v1/rules` 与 cc-import 预览答 `400 request.body_shape`、
+     `GET /v1/rules?scope=` 答 `400 request.query_invalid`、local-import 预览把那一行判 `scope_unreadable`;修前写口答 `503 state.rule_write_failed`「再发一次」(重试永远不会好)、
+     撤销口答 200 而行留在店里、导入预览收下而兑付时被引擎拒。拒句从「with a non-empty root」改成「with an absolute root」。
+   - **SQL 后端(MySQL-protocol / PostgreSQL)起服时一次性删掉存量的这种行**(规则行与墓碑;一行一条运维 warn `permission_rule_row_removed`,带桶键、态(`kind`)、工具名与 root
+     (root 已脱敏),不带规则正文;启动汇总行 `one_time_migrations_applied` 的 `undurableScopeRuleRowsRemoved`)。只有 `kind: "rule"`(仍生效的那几行)的 warn 劝重写:
+     还要的规则按项目的完整路径重新写。`kind: "revoked-rule"`(早已撤销:它背后的每一次同意都被同桶的撤销记录删掉了)与 `kind: "tombstone"`(撤销记录本身)随之删掉,
+     **不要**重加 —— 撤销照旧成立。
+   - **读路径整桶拒的桶一行不动**(形不合、指纹不符、behavior 不认识、撤销记录的规则文本不规范、规则文本与匹配字段不一致 —— 与读规则时整桶拒的判据是同一只):
+     迁移窗内每次起服逐桶一条运维 warn `permission_rule_bucket_unreadable`(桶键 + 拒因,不带规则正文;汇总行 `undurableScopeRuleBucketsUnreadable` 计数),
+     直到**人工处置** —— 处置 = 修正或删除那一行,并按既有指纹算法(`buildRuleBucketChecksum`,算在规则 / 墓碑 / 隔离三列与观测向量上)重算该桶的 `checksum`。
+     这种桶在升级前后都整桶读不出;迁移不替它删行(从一只整桶拒的桶里删行再重算指纹,等于让原本被拒的规则上线)。
+   - **M11 回写与正常写同形**:被改动的桶里 `rules_json` / `tombstones_json` / `quarantined_json` 的旧行(写于 `behavior` 字段之前)都会补上显式 `behavior`
+     (缺席的本义就是 `allow`,补上的就是 `"allow"`,语义不变);`observed_vector_json` 不动;`checksum` 按回写后的字节重算。
+   - **local 后端删不动**:规则在引擎自己的文件店里,引擎的写面对这种 scope 一律拒 —— 那些行照旧每次 run 被丢并告知;撤销口同样删不动(本版的已知边界,候引擎给删除缝)。
+8. **引擎 7.46.0 的 shell 读法**:喂给 shell 标准输入的脚本(`bash <<'EOF' …`、`curl … | sh`、`cat x.sh | bash`、`bash < x.sh`)按 `-c` 文本判 —— 运行时拼出的一律要人答
+   (`dangerous_delete`,`bypassPermissions` 不免;7.119.0 节第 1 条的已知边界由此收掉);读名单里列了写程序(`cp` / `mv` / `mkdir` / `rm` / `rmdir` / `tee` / `touch` / `flock`)的部署,
+   这些调用现在出卡;开放读面且没有 deny 行时,「说不清读哪」不再出强制卡;经链接 / 别名 / 大小写变体 / `cd` 后相对拼写够到受守路径的调用现在出卡或在闸上拒。
+
 ## 7.119.0 —— 场景指派悬空不再静默落 `default`:`DEFAULT_SCENARIO` 不在册 ⇒ 拒启 · 中心指派的场景名本部署没有 ⇒ 该主体的 run 503 · `APPROVAL_REQUIRE` 的「本会话放行」恢复生效
 
 **升级前核查(一句话)**:把 `DEFAULT_SCENARIO`(缺省 `code`)与**中心里每个主体 / 组 / 全局的场景指派**逐名对本部署的在册场景

package/USAGE.md

@@ -1875,9 +1875,11 @@ tag 词表与每条的最坏后果见 `docs/FAIL-OPEN-CENSUS.md`。引擎装配
 (core 给宿主定级的判别词;词表外原样透传并标 `classificationKnown:false`),指标 `runner_config_advisory_total`
 按 `code` / `classification` / `level` 打标;其中 `shell-gate-off` 在本 session 显式声明 `permissionMode:
 "bypassPermissions"` 时是调用方要的姿态,降为 **info** 并标 `expected`——只有没表态落到引擎默认 off 的无壳直连
-形才 warn。子代 `agents[].denyTools` / `allowTools` 的**名字**也归引擎开跑前一只判、同落这一行:无人挂的名只告不拒;**本服务部署形上退役拼法 / 大小写孪生
-(`bash` / `BASH`)也只告不拒**(委派工具带逐次注入的 extraTools,引擎列不全子代工具池),名字按工具名原拼写 `Bash`;且这两张表只约束**委派池**里的工具 ——
-内建 hands 带的工具(如 `Write`)不受 `denyTools` 约束(引擎后续版本一张表盖全),今天要对子代藏内建工具用会话策略 `toolDeny` / 部署 deny 规则。
+形才 warn。子代 `agents[].denyTools` / `allowTools` 的**名字**也归引擎开跑前一只判、同落这一行:无人挂的名只告不拒;退役拼法 / 大小写孪生(`bash` / `BASH`)
+**开跑前拒**(`config.agent.unknown_tool`;委派工具声明了逐次注入工具的名册,引擎列得出子代工具池),名字按工具名原拼写 `Bash`。这两张表管子代手里的**全部**
+工具 —— 委派池与内建 hands(`Read` / `Edit` / `Write` / `NotebookEdit` / `Bash` / `Grep` / `Glob` …):`denyTools:["Write"]` ⇒ 子代没有 `Write`;`allowTools` 只列
+调用方工具 ⇒ 子代一只内建 hands 工具都没有(要什么就点名什么)。内建只读子代(Explore / Plan)没有 `Edit` / `Write` / `NotebookEdit`。hands 之外的引擎工具(`Monitor`
+等)仍不受这两张表管;要按路径 / 命令拦而保留工具,写调用方权限策略的 deny 规则。
 
 🔴 **`shell-gate-off` 这条注的语义自 7.73.0(core 7.15.0)起收窄,文案由引擎改写**:`off` 档**不再**意味着
 「这条会话的 shell 完全没有门」。**读边界**(内建读拒表 + 工作区容纳面)现在**每一档都判**,`shellGate` 只管

package/dist/boot/config-center.js

@@ -316,7 +316,7 @@ export async function createConfigCenterRuntime(ctx) {
     };
     let bootConfigPending;
     const lkgEnabled = configProvider?.kind === "remote" && configLkgEnabled();
-    const lkgPathFor = (identity) => process.env.CONFIG_LKG_PATH ?? defaultLkgPath(cc?.worker, identity);
+    const lkgPathFor = (identity) => config.configLkgPath ?? defaultLkgPath(config, cc?.worker, identity);
     const lkgSurvivesRestart = lkgEnabled && process.env.CONFIG_LKG_DURABLE === "true";
     let lkgBooted = false;
     let bootLkgCandidate;
@@ -335,10 +335,10 @@ export async function createConfigCenterRuntime(ctx) {
         const lkgPath = lkgPathFor(identity);
         try {
             if (effectiveObj.skills && config.configCenter) {
-                await applyCenterSkills([], effectiveObj.skills, config.configCenter, logger, undefined, defaultSkillCacheDir());
+                await applyCenterSkills([], effectiveObj.skills, config.configCenter, logger, undefined, defaultSkillCacheDir(config));
             }
             const enabledSkills = (effectiveObj.skills?.skills ?? []).filter((m) => m.enabled !== false);
-            const cacheDir = defaultSkillCacheDir();
+            const cacheDir = defaultSkillCacheDir(config);
             for (const m of enabledSkills) {
                 const hex = m.contentHash.replace(/^sha256:/, "").toLowerCase();
                 if (!SHA256_HEX_RE.test(hex))
@@ -375,7 +375,7 @@ export async function createConfigCenterRuntime(ctx) {
                 return null;
             }
             const lkgPath = lkgPathFor(identity);
-            const legacy = await migrateV1Lkg({ legacyPath: process.env.CONFIG_LKG_PATH ?? legacyV1LkgPath(cc?.worker), binPath: lkgPath, worker: cc?.worker, identity });
+            const legacy = await migrateV1Lkg({ legacyPath: config.configLkgPath ?? legacyV1LkgPath(config, cc?.worker), binPath: lkgPath, worker: cc?.worker, identity });
             switch (legacy.outcome) {
                 case "none":
                     break;
@@ -622,7 +622,7 @@ export async function createConfigCenterRuntime(ctx) {
         },
         async applyCenterCapabilities(skills) {
             if (effective?.skills && config.configCenter) {
-                skills = await applyCenterSkills(skills, effective.skills, config.configCenter, logger, undefined, configLkgEnabled() ? defaultSkillCacheDir() : undefined);
+                skills = await applyCenterSkills(skills, effective.skills, config.configCenter, logger, undefined, configLkgEnabled() ? defaultSkillCacheDir(config) : undefined);
             }
             if (effective?.plugins !== undefined) {
                 const pluginOut = await applyCenterPlugins(skills, effective, {

package/dist/boot/execution-env.js

@@ -205,9 +205,10 @@ export function createExecutionEnv(ctx) {
     }
     else if (config.remoteExec?.provider === "host") {
         {
+            const schedulerStorePath = config.schedulerStorePath ?? defaultSchedulerStorePath(config);
             const hostScheduler = facts.hostScheduler(config).available
                 ? new FileSchedulerBackend({
-                    ...(config.schedulerStorePath ? { storePath: config.schedulerStorePath } : {}),
+                    storePath: schedulerStorePath,
                     ...(config.schedulerSessionWakeup === false || config.schedulerSessionLifetime === false
                         ? {
                             caps: {
@@ -219,7 +220,7 @@ export function createExecutionEnv(ctx) {
                 })
                 : undefined;
             if (hostScheduler)
-                logger.info(`R7: self-wake scheduler enabled (host lane), store=${config.schedulerStorePath ?? defaultSchedulerStorePath()}`);
+                logger.info(`R7: self-wake scheduler enabled (host lane), store=${schedulerStorePath}`);
             const hostCfg = {
                 ...homeDirSeat,
                 ...(config.remoteExec.workspaceBase ? { workspaceBase: config.remoteExec.workspaceBase } : {}),

package/dist/boot/fatal-exit.d.ts

@@ -1,4 +1,10 @@
-/** `err` 的 fatal 日志文本:`String(err)` 过形状律一次。纯函数,零副作用。 */
+/**
+ * `err` 的 fatal 日志文本:标题过形状律一次。纯函数,零副作用。
+ *
+ * 标题 = `String(err)`;异常**自带机器码**(`err.code` 是串 —— 引擎的构造期拒因都带,如 `config.agent_config_dir_invalid`)⇒ 按 Node 给自家
+ * 带码异常的写法 `<name> [<code>]: <message>` 把码写进标题(`String(err)` 不带 `code`,修前拒启行里看不到引擎的码)。一条规则,不分谁铸的:
+ * 多数 Node 自己的 `ERR_*` 异常本来就印成这一形(逐字不变),系统调用异常(`EEXIST` 等)标题里多一次码。
+ */
 export declare function buildFatalErrorText(err: unknown): string;
 /**
  * 进程级 fatal 出口的**唯一一只腿**:同一只 {@link buildFatalErrorText} 产物写两个面,然后按崩溃码退。

package/dist/boot/fatal-exit.js

@@ -1,7 +1,8 @@
 import { redactSecrets } from "../trace/redact.js";
 import { createLogger } from "../observability/logger.js";
 export function buildFatalErrorText(err) {
-    return redactSecrets(String(err));
+    const code = err instanceof Error ? err.code : undefined;
+    return redactSecrets(typeof code === "string" && err instanceof Error ? `${err.name} [${code}]: ${err.message}` : String(err));
 }
 export function fatalExit(err) {
     const text = buildFatalErrorText(err);

package/dist/boot/runner-deps.d.ts

@@ -311,9 +311,10 @@ export declare function createEngineNoticeSeat(logger: {
  * 「键为 undefined」与「键缺席」对引擎逐字等价)。**不复制引擎缺省**(`roots`/`static-face`/`carry`/`open`/
  * CC parity 20/200 一个都不抄):上游改缺省之日起本仓不会成为第二份真源。
  */
-export type DeploymentPostureSeats = Pick<RunnerDeps, "readFace" | "readDenyPatterns" | "readDenyBuiltinTiers" | "readDenyBuiltinExclude" | "memoryDelegationEvidence" | "memoryProvenance" | "memoryCapturePolicy" | "delegationEntryCaps" | "crossSessionInbound" | "crossSessionDialogExpiry" | "writeProtectedPaths" | "allowedTools">;
-/** 本族读的配置切面:席名与 config 键同名的那几席 + 运维 allow 表(席 `allowedTools` ← config `approvalGrant`,env 名 `APPROVAL_GRANT` 不改)。 */
-export type DeploymentPostureConfig = Pick<ServiceConfig, Exclude<keyof DeploymentPostureSeats, "allowedTools"> | "approvalGrant">;
+export type DeploymentPostureSeats = Pick<RunnerDeps, "readFace" | "readDenyPatterns" | "readDenyBuiltinTiers" | "readDenyBuiltinExclude" | "memoryDelegationEvidence" | "memoryProvenance" | "memoryCapturePolicy" | "delegationEntryCaps" | "crossSessionInbound" | "crossSessionDialogExpiry" | "writeProtectedPaths" | "allowedTools" | "agentConfigDir">;
+/** 本族读的配置切面:席名与 config 键同名的那几席 + 运维 allow 表(席 `allowedTools` ← config `approvalGrant`,env 名 `APPROVAL_GRANT` 不改)
+ *  + LKG 覆写路径(`readDenyPatterns` 席并入它派生的读拒行,`lkgReadDenyRows`)。 */
+export type DeploymentPostureConfig = Pick<ServiceConfig, Exclude<keyof DeploymentPostureSeats, "allowedTools"> | "approvalGrant" | "configLkgPath">;
 export declare function buildDeploymentPostureSeats(config: DeploymentPostureConfig): DeploymentPostureSeats;
 export declare function createSharedRunnerDeps(ctx: SharedRunnerDepsCtx): SharedRunnerDeps;
 export declare function createRunnerDeps(ctx: RunnerDepsCtx): RunnerDeps;

package/dist/boot/runner-deps.js

@@ -1,6 +1,7 @@
 import { createFileWorkflowScriptStore } from "@sema-agent/core";
 import { join } from "node:path";
 import { listCollabWorkflows, resolveCollabWorkflow } from "../capabilities/collab-workflows.js";
+import { lkgReadDenyRows } from "../config-lkg.js";
 import { fleetBackgroundChildPublisher, FleetEventBus } from "../fleet/fleet-bus.js";
 import { createMemoryEngineIncidentSink } from "../memory-incident-sink.js";
 import { createMemorySessionIncarnationSeat, sessionFaceReaderOf } from "./session-incarnation-seat.js";
@@ -9,7 +10,7 @@ import { createHardenedVmRunner } from "../orchestration/hardened-vm-runner.js";
 import { createWorkerHardenedVmRunner } from "../orchestration/hardened-vm-worker-runner.js";
 import { WorkflowAgentRegistry } from "../orchestration/workflow-agent-steer.js";
 import { resolveServedSession } from "../orchestration/workflow-completion-inbox.js";
-import { defaultEngineNoticeRouter, presentNoticeDetail } from "../trace/engine-notice-wire.js";
+import { defaultEngineNoticeRouter, redactNoticeRuleText } from "../trace/engine-notice-wire.js";
 import { WorkflowNotifyGate } from "../orchestration/workflow-notify-journal.js";
 import { makeLoadProjectMemory, makeProbeInstructionSources } from "../project-memory.js";
 import { createInstructionSourceSeat } from "../instruction-source-notice.js";
@@ -41,7 +42,7 @@ const PROMPT_CACHE_BREAK_LEVELS = new Map(Object.entries(PROMPT_CACHE_BREAK_CAUS
 const CEILING_ORIGINS = new Set(["walltime", "turns"]);
 export function createEngineNoticeForwarder(logger, router = defaultEngineNoticeRouter, metrics) {
     return (notice) => {
-        const detail = presentNoticeDetail(notice.code, notice.detail);
+        const detail = redactNoticeRuleText(notice.code, notice.detail);
         logger.warn("engine_notice", { code: notice.code, message: notice.message, ...(detail !== undefined ? { detail } : {}) });
         if (metrics !== undefined && notice.code === "task.interrupt_unconsumed") {
             const origin = notice.detail?.origin;
@@ -57,11 +58,14 @@ export function createEngineNoticeSeat(logger, router = defaultEngineNoticeRoute
 }
 export function buildDeploymentPostureSeats(config) {
     const crossSessionLayers = buildCrossSessionInboundLayers(config);
+    const lkgRows = lkgReadDenyRows(config.configLkgPath);
+    const readDenyAdditions = lkgRows.length === 0 ? config.readDenyPatterns : [...(config.readDenyPatterns ?? []), ...lkgRows];
     const seats = {
         readFace: config.readFace ? config.readFace : undefined,
-        readDenyPatterns: config.readDenyPatterns ? config.readDenyPatterns : undefined,
+        readDenyPatterns: readDenyAdditions ? readDenyAdditions : undefined,
         readDenyBuiltinTiers: config.readDenyBuiltinTiers ?? undefined,
         readDenyBuiltinExclude: config.readDenyBuiltinExclude ?? undefined,
+        agentConfigDir: config.agentConfigDir ?? undefined,
         memoryDelegationEvidence: config.memoryDelegationEvidence ?? undefined,
         memoryProvenance: config.memoryProvenance ?? undefined,
         memoryCapturePolicy: config.memoryCapturePolicy ?? undefined,

package/dist/boot/stage-01-config.js

@@ -13,6 +13,7 @@ import { installSecretEnvScrubRecorder } from "../observability/secret-env-scrub
 import { setRunTerminalLogObserver } from "../observability/run-terminal.js";
 import { setRedactionObserver } from "../trace/redact.js";
 import { installOutboundDispatcher } from "../outbound-dispatcher.js";
+import { provisionSemaConfigDir } from "../sema-config-dir.js";
 export function runStage01() {
     const config = loadConfig();
     const runStaleFailure = crossInvariant("run-stale-heartbeat").check({ live: config, next: config });
@@ -44,6 +45,7 @@ export function runStage01() {
         else
             logger.info("run_failed", fields);
     });
+    provisionSemaConfigDir(config, logger);
     const localRoot = configLocalRoot(config);
     const rootsSplit = splitLocalRoots({
         localDataRoot: config.localDataRoot,

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

@@ -1,19 +1,42 @@
-import type { SubagentSpawnContext, ToolSpec } from "@sema-agent/core";
+import type { SubagentSpawnContext, SubagentToolOptions, ToolSpec } from "@sema-agent/core";
 /** Current time — the model has no clock; OA/most tasks need it. No side effects. CC-parity tool name `Now`
  *  (PascalCase, core 1.176 first-party rename wrap-up — the SERVICE owns this one; `nowTool` is not a core tool).
  *  effect:"read" so it never suspends → no durable-resume rename strand (no pending-tool checkpoint to canonicalize). */
 export declare function nowTool(): ToolSpec;
 /**
- * #1110(core 7.32.0)—— 委派子代的**逐次注入**工厂(`SubagentToolOptions.extraTools`):`Now` + 部署的 extra tools(今天 = SendUserFile)。
+ * 委派子代逐次注入的**一组**工具:`tools` 是这组**可能**注入的全部工具对象,`forSpawn` 只在这些对象里选「这一次 spawn 拿不拿」(缺席 = 每次都拿)。
+ * 名册与工厂读的是同一张 `tools` —— 工厂只能交出名册里那几只对象,结构上交不出名册外的东西(core 7.46.0 #1432 的「声明不说谎」在本仓由形状保证,
+ * 不靠两张表对拍)。
+ */
+export interface SubagentExtraToolSet {
+    readonly tools: readonly ToolSpec[];
+    readonly forSpawn?: (ctx: SubagentSpawnContext) => boolean;
+}
+/** 委派工具上与逐次注入相关的两键(core `SubagentToolOptions` 的 `extraTools` / `extraToolNames`):工厂(本仓的恒同步)+ 它的名册。 */
+export interface SubagentExtraToolOptions {
+    readonly extraTools: (ctx: SubagentSpawnContext) => ToolSpec[];
+    readonly extraToolNames: NonNullable<SubagentToolOptions["extraToolNames"]>;
+}
+/**
+ * #1110(core 7.32.0)—— 委派子代的**逐次注入**:`Now` + 部署的 extra tools(今天 = SendUserFile)。
  *
  * 为什么 `Now` 走这条通道:core 7.32.0 起子代按**身份**继承场景层 bundle 的工具(`assembleCodeTools` 交给 Agent 的
  * `inheritedTools` ∩ 父 run 真挂载),而 `Now` 是本仓在 bundle **旁边**组的宿主工具(scenarios.ts),宿主工具**从不**被继承
  * (core:继承整张 `spec.tools` 会把宿主工具带过宿主自己的逐次门)—— 逐次注入是它到达子代的唯一通道。一个工厂、两个产地:
- * 部署工厂的门(SendUserFile 的审批面预判 / 只读内建排除)原样在它自己那只函数里,这里只做合成。
- * ⚠️ 工厂恒在场 ⇒ core 不再给 Agent 工具铸静态 `agentToolPool`(core:工厂可在 spawn 时注入身份未知的工具 ⇒ 池不可静态知 ⇒
- * 记忆内容来源读者按「外部」读,fail-closed)。本仓 default bundle 的继承面本来就含 WebFetch(外部),这一翻面只在
- * 「子代面恰好不含任何外部工具」的窄形上把委派结果多判一次外部,方向是收紧。
- * 工厂**不抛**:`nowTool()` 是纯构造;部署工厂的抛由 core 收成「这一 spawn 什么都不继承 + 模型面披露句」(onExtraToolsError 记 warn)。
+ * 部署那一组的门(只读内建排除)在它自己的 `forSpawn` 里,这里只做合成。
+ *
+ * core 7.46.0 #1432 —— **工厂与名册一个来源**:返回委派工具的两键,`extraTools`(每次 spawn 交出 `forSpawn` 选中的那几只)与
+ * `extraToolNames`(全部可能交出的那几只的名字 / 别名 / 内容来源,从同一批 `ToolSpec` 读出)。名册在场 ⇒ 引擎重新能列出子代的工具池:
+ * 定义级 / 工具级 / `TaskSpec.agents` 清单里的退役拼法与大小写孪生回到开跑前拒(`config.agent.unknown_tool`),记忆内容来源读者按声明读这几只。
+ * 修前(core 7.32.0–7.45.x)工厂恒在场 ⇒ 池不可静态知 ⇒ 那一族拼法只告不拒、委派结果一律按「外部」读。
+ * 工厂**不抛**:各组的 `tools` 是装配期就建好的对象;部署 `forSpawn` 的抛由 core 收成「这一 spawn 什么都不继承 + 模型面披露句」(onExtraToolsError 记 warn)。
+ * 一种拼法出现在两只工具上(部署工具与 `Now` 撞名 / 别名撞)⇒ core 在建委派工具处抛 `config.extra_tool_names`(`shape`),不静默取其一。
+ */
+export declare function createSubagentExtraTools(deployment?: SubagentExtraToolSet): SubagentExtraToolOptions;
+/**
+ * `onExtraToolsError` 收到的错误 → 运维行 `subagent_extra_tools_error` 的字段:句子,加上错误**自带**的码与 `detail.reason`(在场才铸)。
+ * core 7.46.0 #1432 被拒的 spawn(产物不在名册里)带 `config.extra_tool_names` + `undeclared_name` / `undeclared_origin`;部署工厂自己抛的错多半两位都不带。
+ * 本仓不按码分支、不重铸 —— 只把错误说的话原样过境到运维面(修前只记句子,码与原因词丢在这一跳)。
  */
-export declare function createSubagentExtraTools(deployment?: (ctx: SubagentSpawnContext) => ToolSpec[]): (ctx: SubagentSpawnContext) => ToolSpec[];
+export declare function extraToolsErrorFields(err: unknown): Record<string, unknown>;
 //# sourceMappingURL=builtin-tools.d.ts.map

package/dist/capabilities/builtin-tools.js

@@ -9,6 +9,27 @@ export function nowTool() {
     };
 }
 export function createSubagentExtraTools(deployment) {
-    return (ctx) => [nowTool(), ...(deployment?.(ctx) ?? [])];
+    const sets = [{ tools: [nowTool()] }, ...(deployment !== undefined ? [deployment] : [])];
+    return {
+        extraTools: (ctx) => sets.flatMap((s) => (s.forSpawn === undefined || s.forSpawn(ctx) ? [...s.tools] : [])),
+        extraToolNames: sets.flatMap((s) => s.tools).map((t) => ({
+            name: t.name,
+            ...(t.aliases !== undefined ? { aliases: [...t.aliases] } : {}),
+            ...(t.contentOrigin !== undefined ? { contentOrigin: t.contentOrigin } : {}),
+        })),
+    };
+}
+export function extraToolsErrorFields(err) {
+    const fields = { err: err instanceof Error ? err.message : String(err) };
+    if (err === null || typeof err !== "object")
+        return fields;
+    const code = Reflect.get(err, "code");
+    if (typeof code === "string")
+        fields.code = code;
+    const detail = Reflect.get(err, "detail");
+    const reason = detail !== null && typeof detail === "object" ? Reflect.get(detail, "reason") : undefined;
+    if (typeof reason === "string")
+        fields.reason = reason;
+    return fields;
 }
 //# sourceMappingURL=builtin-tools.js.map

package/dist/capabilities/scenarios.d.ts

@@ -1,6 +1,7 @@
-import { type WebFetchConfig, type BackgroundAgentStore, type CheckpointStore, type PromptProvider, type Runner, type SkillSpec, type SubagentSpawnContext, type TaskListStore, type ToolSpec, type WebSearchConfig } from "@sema-agent/core";
+import { type WebFetchConfig, type BackgroundAgentStore, type CheckpointStore, type PromptProvider, type Runner, type SkillSpec, type TaskListStore, type ToolSpec, type WebSearchConfig } from "@sema-agent/core";
 import type { Metrics } from "../observability/metrics.js";
 import type { Logger } from "../observability/logger.js";
+import { type SubagentExtraToolSet } from "./builtin-tools.js";
 import { type RepoReadClient } from "./repo-tools.js";
 import { type LoadedSkill } from "./skills.js";
 import { type ScenarioHands } from "./hands-lane.js";
@@ -90,12 +91,13 @@ export interface ScenarioDeps {
      * core 1.287 `SubagentToolOptions.extraTools` seam wire-through — per-SPAWN dynamic tool injection into the
      * delegated (Agent-tool) child roster. Deployment-injected per-task tools (today: SendUserFile — its instance is
      * execute-time late-bound via ctx.taskId → TaskEnvRegistry, so ONE spec serves every spawn) cannot ride the
-     * ASSEMBLY-time static `subagent.tools` pool; this factory is evaluated by core at each spawn and its product is
-     * merged into the pool, then goes through core's `resolveToolSubset` whitelist like any other tool (agent-def
-     * allowTools/denyTools still govern — no extra gate needed on our side). Absent ⇒ no dynamic injection (children
-     * see exactly the static full-body roster, the pre-1.287 behavior).
+     * ASSEMBLY-time static `subagent.tools` pool; core evaluates the factory at each spawn and merges its product into the
+     * pool, then it goes through core's `resolveToolSubset` whitelist like any other tool (agent-def allowTools/denyTools
+     * still govern — no extra gate needed on our side). A SET, not a bare factory (core 7.46.0 #1432): its `tools` are both
+     * what a spawn can be handed and the roster the delegation tool declares (`extraToolNames`), so the factory cannot hand
+     * out a tool the roster does not name. Absent ⇒ the delegation tool injects `Now` alone.
      */
-    subagentExtraTools?: (ctx: SubagentSpawnContext) => ToolSpec[];
+    subagentExtraTools?: SubagentExtraToolSet;
     /**
      * core 1.364 durable background agents([ref] S1,[ref] 提货单②写半场):后台子代 `a*` 行的
      * durable 执行记录 store。**必须与 `RunnerDeps.backgroundAgentStore` 同实例**(读写双点配对,engine

package/dist/capabilities/scenarios.js

@@ -1,6 +1,6 @@
 import { CODE_AGENT_PROMPT, CODE_SYSTEM_PROMPT, DEFAULT_SYSTEM_PROMPT, WEB_FETCH_TOOL_NAME, assembleCodeTools, defaultTaskRegistry } from "@sema-agent/core";
 import { HttpError, createCodedHttpError } from "../security.js";
-import { createSubagentExtraTools, nowTool } from "./builtin-tools.js";
+import { createSubagentExtraTools, extraToolsErrorFields, nowTool } from "./builtin-tools.js";
 import { parseRepo, repoToolsFor } from "./repo-tools.js";
 import { createCouncilTool, clampRounds } from "./code-review-council.js";
 import { stablePrompt } from "./prompt.js";
@@ -70,9 +70,9 @@ export function buildScenarios(deps) {
                             ...(deps.checkpointStore ? { checkpointStore: deps.checkpointStore } : {}),
                             ...(deps.ensureChildSessionDurable ? { ensureChildSessionDurable: deps.ensureChildSessionDurable } : {}),
                         },
-                        extraTools: createSubagentExtraTools(deps.subagentExtraTools),
+                        ...createSubagentExtraTools(deps.subagentExtraTools),
                         ...(deps.logger
-                            ? { onExtraToolsError: (err, info) => deps.logger?.warn?.("subagent_extra_tools_error", { ...info, err: err instanceof Error ? err.message : String(err) }) }
+                            ? { onExtraToolsError: (err, info) => deps.logger?.warn?.("subagent_extra_tools_error", { ...info, ...extraToolsErrorFields(err) }) }
                             : {}),
                     },
                     ...(webSearch ? { webSearch } : {}),

package/dist/capabilities/send-user-file-tool.d.ts

@@ -1,5 +1,6 @@
-import type { SubagentSpawnContext, ToolSpec } from "@sema-agent/core";
+import type { ToolSpec } from "@sema-agent/core";
 import type { IssuedFileLink } from "../plugins/send-user-file.js";
+import type { SubagentExtraToolSet } from "./builtin-tools.js";
 /** The frame the web/shell renders as a file card. Rides the durable events tail (replayable). */
 export interface FileLinkFrame {
     type: "file_link";
@@ -44,7 +45,9 @@ export declare function sendUserFileTool(deps: {
 }): ToolSpec;
 export declare const SEND_USER_FILE_TOOL_NAME = "SendUserFile";
 /**
- * Build the `SubagentToolOptions.extraTools` factory that injects SendUserFile into delegated-child rosters.
+ * The deployment's group for the delegated-child injection (`createSubagentExtraTools` in `builtin-tools.ts` composes it with
+ * `Now` into the delegation tool's `extraTools` factory AND its `extraToolNames` roster — one list, read twice): SendUserFile,
+ * handed to every spawn except a read-only builtin agent's.
  *
  * F2 (MED, codex; a product judgment of this server, kept): read-only builtin agents (Explore/Plan) must NOT get
  * SendUserFile — a read-only agent that can read sensitive files AND mint public links off them breaks the read-only
@@ -59,5 +62,5 @@ export declare const SEND_USER_FILE_TOOL_NAME = "SendUserFile";
  */
 export declare function subagentSendUserFileExtraTools(deps: {
     spec: ToolSpec;
-}): (ctx: SubagentSpawnContext) => ToolSpec[];
+}): SubagentExtraToolSet;
 //# sourceMappingURL=send-user-file-tool.d.ts.map

package/dist/capabilities/send-user-file-tool.js

@@ -94,6 +94,6 @@ export function sendUserFileTool(deps) {
 export const SEND_USER_FILE_TOOL_NAME = "SendUserFile";
 const READONLY_BUILTIN_AGENT_TYPES = new Set(builtinAgentDefinitions().map((d) => d.name));
 export function subagentSendUserFileExtraTools(deps) {
-    return (ctx) => (ctx.agentType !== undefined && READONLY_BUILTIN_AGENT_TYPES.has(ctx.agentType) ? [] : [deps.spec]);
+    return { tools: [deps.spec], forSpawn: (ctx) => !(ctx.agentType !== undefined && READONLY_BUILTIN_AGENT_TYPES.has(ctx.agentType)) };
 }
 //# sourceMappingURL=send-user-file-tool.js.map

package/dist/config-catalog.js

@@ -94,7 +94,7 @@ export const CONFIG_CATALOG = [
     r("CONFIG_CATALOG_ENABLED", "auth", "boolean", "本目录端点 GET /v1/config/catalog 的旋钮(operator-only 面;合规部署可关 ⇒ 路径 404 + 能力位翻假)", { staticDefault: "true", danger: SEC, configKey: "configCatalogEnabled" }),
     r("CONFIG_LKG_DURABLE", "integrations", "boolean", "LKG 跨重启 handoff(严格 'true' 才开:重启先用 LKG 起服,tier 候选借此落地)", { staticDefault: "false" }),
     r("CONFIG_LKG_ENABLED", "integrations", "boolean", "last-known-good 配置盘缓存读写开关(仅远程 provider 有意义)", { staticDefault: "true" }),
-    r("CONFIG_LKG_PATH", "integrations", "path", "LKG 落盘路径", { derivedDefaultNote: "缺席 ⇒ SEMA_CONFIG_DIR(~/.sema)下按 worker 名派生" }),
+    r("CONFIG_LKG_PATH", "integrations", "path", "LKG 落盘路径(设了 ⇒ 派生读拒行:这条路径与它的真实落点各一行,按路径段串匹配 —— 任意深度出现即拒、大小写不敏感,用户仓里同段串的路径一并读不到;空串拒启)", { derivedDefaultNote: "缺席 ⇒ 配置根(SEMA_CONFIG_DIR,缺省 ~/.sema)下按 worker + 凭证身份分箱派生", configKey: "configLkgPath" }),
     r("CONFIG_LOCAL_DIR", "integrations", "path", "本地配置源根(config.d/<domain>.json);兼作数据根回落链一环", { configKey: "configLocalDir", danger: DATA }),
     r("CONFIG_PROVIDER", "integrations", "enum", "配置源双模选择(闭集,逐字比较;认不出的词 ⇒ 拒启,S-841)", { enumValues: CONFIG_PROVIDER_WORDS, derivedDefaultNote: "缺席:SEMA_REGISTRY_URL 在场 ⇒ remote,否则纯 env(无管道)", configKey: "configProvider" }),
     r("CONFIG_REQUIRE_ROSTER", "integrations", "boolean", "远程 registry 非 dryRun 时布防 ready 门:roster 未落地 ⇒ 计费提交 503 + /health ready:false(严格 'true')", { staticDefault: "false" }),
@@ -391,7 +391,7 @@ export const CONFIG_CATALOG = [
     r("SELF_ORCHESTRATION_MODELS", "orchestration", "csv", "workflow agent({modelName}) 显式词表(恒赢;缺席单用户=目录键全集/多租户 fail-closed)", { configKey: "selfOrchestrationModels" }),
     r("SELF_ORCHESTRATION_WORKER_ISOLATION", "orchestration", "boolean", "workflow 脚本跑 worker_thread(堆帽+terminate 的 DoS 隔离)", { staticDefault: "false", danger: SEC, configKey: "selfOrchestrationWorkerIsolation" }),
     r("SEMA_APT_MIRROR", "orchestration", "url", "SANDBOX_PKG_SOURCE=custom 的显式 apt 源地址(注入沙箱 pkg-source hook)"),
-    r("SEMA_CONFIG_DIR", "integrations", "path", "~/.sema 配置目录覆写(LKG/skill 缓存/scheduler 店同门)", { derivedDefaultNote: "缺席 ⇒ ~/.sema" }),
+    r("SEMA_CONFIG_DIR", "integrations", "path", "~/.sema 配置目录覆写(LKG/skill 缓存/scheduler 店同门;设了 ⇒ 起服时建出目录,交引擎在根下同护配置文件,能不能用由引擎判;空串拒启)", { derivedDefaultNote: "缺席 ⇒ ~/.sema", configKey: "agentConfigDir" }),
     r("SEMA_FAILOPEN_PROBE", "observability", "path", "F 类 fail-open 命中的探针文件路径(在场时逐次追加 fail-open 行;缺席只走计数+一次性 warn)"),
     r("SEMA_NODE_MIRROR", "orchestration", "url", "SANDBOX_PKG_SOURCE=custom 的显式 node 分发镜像地址"),
     r("SEMA_NPM_REGISTRY", "orchestration", "url", "SANDBOX_PKG_SOURCE=custom 的显式 npm registry 地址"),

package/dist/config-lkg.d.ts

@@ -11,11 +11,37 @@ export interface PersistedLkg {
 /** skill 正文的 content-addressed 盘缓存目录(LKG 的姊妹面):LKG 只含 skills MANIFEST(正文按
  *  hash 另拉)——黑洞中心下 LKG-boot 会在 skill 正文拉取上再挂数秒(live 实测 +5.3s)。正文按
  *  `<dir>/<sha-hex>` 落盘,读侧**必验 hash**(content-addressed 的全部意义;坏文件=忽略重拉)。 */
-export declare function defaultSkillCacheDir(): string;
-/** 默认路径(scheduler store 同门:SEMA_CONFIG_DIR → ~/.sema),按「worker + 凭证身份」分箱。`CONFIG_LKG_PATH`
- *  覆写(单一路径 ⇒ 不分箱,信封的 worker + identity 核仍守读回);`CONFIG_LKG_ENABLED=false` 关闭(读写双关)。
+export declare function defaultSkillCacheDir(config: {
+    readonly agentConfigDir?: string;
+}): string;
+/** 默认路径(scheduler store 同门:配置根 = 配置席 `agentConfigDir` → ~/.sema,{@link configRootOf}),按「worker + 凭证身份」分箱。`CONFIG_LKG_PATH`
+ *  覆写(`config.configLkgPath`,读法 {@link lkgPathOverrideOf};单一路径 ⇒ 不分箱,信封的 worker + identity 核仍守读回);`CONFIG_LKG_ENABLED=false` 关闭(读写双关)。
  *  🪦 正名前的 `CONFIG_LKG_DISABLED` 自 server 3.0.0 起是**fail-loud 墓碑**——设了(任何值)即拒启并指路新名,不再被读取。 */
-export declare function defaultLkgPath(worker: string | undefined, identity: string): string;
+export declare function defaultLkgPath(config: {
+    readonly agentConfigDir?: string;
+}, worker: string | undefined, identity: string): string;
+/**
+ * `CONFIG_LKG_PATH`(LKG 落盘路径覆写)的**唯一读法**:没设 ⇒ `undefined`(LKG 落在配置根下按箱派生,{@link defaultLkgPath});设了 ⇒ 绝对路径
+ * (相对值按进程 cwd 解,与文件被打开时同一个解法);空串 ⇒ 拒(起服拒):空串解出来是进程工作目录本身 —— 一条落盘路径不该是一个目录,
+ * 由它派生的读拒行({@link lkgReadDenyRows})会把整个工作目录读拒掉。`loadConfig` 调它铸 `configLkgPath`,读者只读那一席。
+ */
+export declare function lkgPathOverrideOf(raw: string | undefined): string | undefined;
+/**
+ * LKG(含凭据)实际所在位置的**读拒行** —— 一条规则:读拒从 LKG 落在哪派生,不写死位置。
+ *  · 没覆写 ⇒ LKG 落在配置根下(`config-lkg-<箱>.json`):引擎内建表的 `~/.sema/config-lkg-*.json` 行在家目录与声明的根(`agentConfigDir`,
+ *    根经链接时引擎连目标一起守)两处守它 ⇒ 不另加行(加了就是同一个文件两只判据,`READ_DENY_BUILTIN_EXCLUDE` 删那一行也删不掉它);
+ *  · 覆写 ⇒ LKG 在配置根外,引擎那一行够不着 ⇒ 这里派生行:它的**两种拼法**各一行 —— 覆写写下的绝对路径,与文件真正落的地方(路径经符号链接的
+ *    目录时,写进去的文件在链接目标下;只守拼写的话读真实路径就绕过了 —— 车内复审 [high])。两者相同 ⇒ 一行。大小写不敏感(与内建行同读法)。
+ *    拒句与内建行同一句(`sensitive-path read deny list (pattern …)`)。
+ *    **行的射程**(引擎读拒表的读法,不是本函数选的):行是路径段串 —— 引擎去掉开头的 `/`、不锚到根,这串段在任意深度出现即拒(大小写不敏感),
+ *    所以挡的不止 LKG 那一个文件:用户仓里同段串的路径(`/app/config-lkg.json` ⇒ `…/app/config-lkg.json`)一并读不到、Grep 结果里也不出现。
+ *    挡多了优于不挡;引擎提供锚定单文件的行之前如此(随包文案 MIGRATION / 目录行同句)。
+ * 读者:部署姿态座席族(`boot/runner-deps.ts` `buildDeploymentPostureSeats` 的 `readDenyPatterns` 席 = 运维的行 ∪ 本函数的行)—— 每次铸席现解一次链接。
+ */
+export declare function lkgReadDenyRows(configLkgPath: string | undefined): {
+    pattern: string;
+    caseSensitive: boolean;
+}[];
 /** 原子落盘一个干净候选(tmp+rename,0600)。BEST-EFFORT:失败=一条 warn 的素材(调用方发),绝不
  *  影响在飞的应用链——LKG 缓存丢失的代价只是下次冷启动回到 env 兜底。 */
 export declare function saveLkg(path: string, worker: string | undefined, identity: string, effective: Record<string, unknown>, etag: string | undefined): Promise<void>;
@@ -31,7 +57,9 @@ export declare function loadLkg(path: string, worker: string | undefined, identi
     reason: string;
 }>;
 /** 7.98.0 及以前的默认 LKG 路径(按当时的写法逐字保留 —— 这是盘上已有文件的名字,不是现行分箱规则)。 */
-export declare function legacyV1LkgPath(worker: string | undefined): string;
+export declare function legacyV1LkgPath(config: {
+    readonly agentConfigDir?: string;
+}, worker: string | undefined): string;
 export type LegacyLkgMigration = {
     readonly outcome: "none";
 }

package/dist/config-lkg.js

@@ -1,15 +1,60 @@
-import { promises as fs } from "node:fs";
-import { homedir } from "node:os";
-import { join, dirname } from "node:path";
+import { promises as fs, lstatSync, realpathSync } from "node:fs";
+import { basename, join, dirname, resolve } from "node:path";
 import { randomBytes } from "node:crypto";
 import { validatePromptsDomain } from "./prompts-domain-validate.js";
 import { centerStateBin, pullTokenIdentity } from "./center-credential.js";
-export function defaultSkillCacheDir() {
-    return join(process.env.SEMA_CONFIG_DIR ?? join(homedir(), ".sema"), "skill-cache");
+import { configRootOf } from "./sema-config-dir.js";
+import { recordFailOpen } from "./observability/fail-open.js";
+export function defaultSkillCacheDir(config) {
+    return join(configRootOf(config), "skill-cache");
 }
-export function defaultLkgPath(worker, identity) {
-    const dir = process.env.SEMA_CONFIG_DIR ?? join(homedir(), ".sema");
-    return join(dir, `config-lkg-${centerStateBin(worker, identity)}.json`);
+export function defaultLkgPath(config, worker, identity) {
+    return join(configRootOf(config), `config-lkg-${centerStateBin(worker, identity)}.json`);
+}
+export function lkgPathOverrideOf(raw) {
+    if (raw === undefined)
+        return undefined;
+    if (raw === "") {
+        throw new Error('env CONFIG_LKG_PATH="" is empty — refusing to start: an empty path resolves to the working directory itself, which is no file the last-known-good ' +
+            "config can be kept in. Unset the variable to keep the LKG below the configuration root (SEMA_CONFIG_DIR, default ~/.sema), or set it to the file path you mean.");
+    }
+    return resolve(raw);
+}
+export function lkgReadDenyRows(configLkgPath) {
+    if (configLkgPath === undefined)
+        return [];
+    return [...new Set([configLkgPath, landedPathOf(configLkgPath)])].map((pattern) => ({ pattern, caseSensitive: false }));
+}
+function landedPathOf(p) {
+    const rest = [];
+    let landed = p;
+    let unresolved;
+    for (let head = p;; head = dirname(head)) {
+        try {
+            landed = join(realpathSync(head), ...rest);
+            break;
+        }
+        catch {
+            if (unresolved === undefined && head !== p && segmentPresent(head))
+                unresolved = head;
+            if (dirname(head) === head)
+                break;
+            rest.unshift(basename(head));
+        }
+    }
+    if (unresolved !== undefined)
+        recordFailOpen("server.config-lkg.landed-path-unresolved", `segment=${unresolved}`);
+    return landed;
+}
+function segmentPresent(p) {
+    try {
+        lstatSync(p);
+        return true;
+    }
+    catch (e) {
+        const code = e.code;
+        return code !== "ENOENT" && code !== "ENOTDIR";
+    }
 }
 export async function saveLkg(path, worker, identity, effective, etag) {
     const body = { formatVersion: 2, savedAt: new Date().toISOString(), worker: worker ?? "global", identity, ...(etag !== undefined ? { etag } : {}), effective };
@@ -79,10 +124,9 @@ function lkgPayloadProblem(effective, etag) {
         return "prompts face fails re-validation";
     return undefined;
 }
-export function legacyV1LkgPath(worker) {
-    const dir = process.env.SEMA_CONFIG_DIR ?? join(homedir(), ".sema");
+export function legacyV1LkgPath(config, worker) {
     const key = (worker ?? "global").replace(/[^a-zA-Z0-9._-]/g, "_").slice(0, 64);
-    return join(dir, `config-lkg-${key}.json`);
+    return join(configRootOf(config), `config-lkg-${key}.json`);
 }
 export async function migrateV1Lkg(o) {
     const refuse = (why) => ({