@sema-agent/server 7.81.0 → 7.82.0

package/USAGE.md

@@ -1137,6 +1137,33 @@ curl -N http://<host>:8090/v1/tasks/stream -H 'content-type: application/json' \
 >   ④**模型座位解析不出来**——既没有显式 chat 席,也没有 `roles.consolidate` / `roles.summarize`(含档位表的
 >   `flash` 绑定)。core **刻意不回落主模型**(整库蒸馏不该悄悄骑最贵的席位),本服务照抄那条判断,不在下游
 >   补一个兜底席。
+> - `MEMORY_AUTO_CONSOLIDATION=on|off`(**未设 = 读引擎缺省**,见下):记忆**自动整理**的部署席
+>   (core 7.21.0 的 `RunnerDeps.autoRunOnRecommendation` 席)。武装 ⇒ **每个产生了整理建议的任务
+>   之后**,为该 scope 起**一次**整库整理跑 —— 🔴 **记忆内容自动外流到配置的整理模型**。
+>   **三态,别读成布尔**:
+>   - **未设** = 不写引擎那个键 ⇒ 读引擎的具名缺省,而**本版装的引擎那个缺省是「开」**。
+>     ⇒ 🔴 **不配这根旋钮 = 武装**(在下面那条前置满足时)。缺省的属主在引擎侧、会随提货漂,所以
+>     「什么都不配」这一态的含义**不是稳定的**;要一个稳定的答案就显式写一个词。
+>   - `off` = **显式关,胜过缺省** —— 这是**关闭口**。不想让记忆自动外流的部署,靠它在 core 把缺省翻开
+>     之后仍然保持关闭。**这是本旋钮存在的理由。**
+>   - `on` = 武装。**设之前请先读**「这是出口决定不是性能旋钮」那一句:一轮 consolidation 读**全库**
+>     (~1e5 prompt tokens)并把内容交给整理模型,既是钱更是**数据出境**。
+>   ⚠️ **闭集两词,别的一律拒启**(与上一根同一条纪律,方向在这根上更要紧:一个被读成「未设」的拼错关词
+>   会让那台部署跟着 core 的新缺省**静默武装**,而运维手里握着一份自以为关掉了的配置)。
+>   🔴 **前置 = 上一根旋钮**:引擎面的整理两席(协议席 + 模型席)在场 **iff** `MEMORY_CONSOLIDATION_DRIVER=on`
+>   且记忆引擎接了线 —— 两席与那两个 operator 口**共用同一只已解析座**(不做第二份装配)。
+>   · 阀门关着 ⇒ 两席都不写键,引擎那半场**逐字节不变**;此时 `MEMORY_AUTO_CONSOLIDATION=on`
+>     **启动期响亮拒**(core 对「武装但没接整理席」是**每一次 prepare 都抛** `config.auto_consolidation`,
+>     留到运行期就是一台**启动成功、每个任务都死**的机器)。
+>   · 阀门开着 ⇒ 两席齐 ⇒ 缺省(开)当场生效。
+>   🔴🔴 **升级影响**:**升级前就配了 `MEMORY_CONSOLIDATION_DRIVER=on` 的部署,升到本版之后每个产生了
+>   整理建议的任务之后会自动跑一轮整库整理**(升级前那是只能由人按的手动阀门)。不想要就**升级前**显式写
+>   `MEMORY_AUTO_CONSOLIDATION=off` —— **不配不等于关**。启动日志 `memory_consolidation_driver_armed`
+>   带一位 `autoRunOnRecommendation`(三态原样),用它核这台机器是哪一态。
+>   **两根的分工**:上一根决定**有没有**整理能力,这一根决定那个能力**要不要自动触发**;关掉自动整理,
+>   手动阀门照常可用。
+>   未武装的部署,`wiring_manifest` 与它的 `configFingerprint` 对 7.20.1 **逐字节相同**;武装的部署,新段
+>   `autoConsolidation: { onRecommendation: true }` **只出现在 operator 帧上**(契约附录 G.13)。
 > - `MEMORY_CONSOLIDATION_SCOPES=user:local[,org:acme]`:阀门的 scope 表 = 这台 worker **声明**它会折叠哪些库。
 >   **恰好一条**时它是两个口省略 `scope` 的唯一缺省;零条或多条时省略 `scope` 一律 400(在两个库之间替人挑
 >   一个去花全库模型钱是本设计要消灭的形)。**表非空时显式 scope 必须在表里**,否则 400 —— 一个陈旧或敲错

package/dist/boot/memory-consolidation.d.ts

@@ -138,6 +138,44 @@ export declare function buildStopDetailAudit(input: {
     outcome: string;
     untrustedDetail: string;
 };
+/**
+ * S-362 / S-399 —— **`RunnerDeps.autoRunOnRecommendation` 武装席的装配不变量**(D1 的姊妹门)。
+ *
+ * 与 {@link assertConsolidationDriverWirable} 刻意**分家**而不是加第四臂:那道门问「阀门这根旋钮
+ * (`MEMORY_CONSOLIDATION_DRIVER`)开着而这台机器结构上跑不了」,本门问「武装这根旋钮
+ * (`MEMORY_AUTO_CONSOLIDATION`)开着而引擎那半场没有整理席」。两句诊断指向的动作不同,合成一道门就会
+ * 指错方向。
+ *
+ * ## 为什么是**拒启**而不是让 core 在 prepare 抛
+ *
+ * core 对「`autoRunOnRecommendation: true` 但没接整理席」的处置是**每一次 prepare 都抛**
+ * `config.auto_consolidation`(带码错,不是通知;逐字见 core `RunnerDeps.autoRunOnRecommendation` 的 d.ts)。
+ * 留到运行期买到的是一台**启动成功、每一个任务都死**的 worker —— 比阀门那三条(「启动成功、什么都没
+ * 折叠」)更坏。所以按 D1 的同一条(**安全/成本控件不得半开**)提前到启动期,并把**该去拧哪根**写进句子。
+ *
+ * ## 判据取的是**结构事实**,不是一个手抄的布尔
+ *
+ * `memoryConsolidationWired` 由调用点从**它刚刚铸出来的那只 `RunnerDeps`** 上读(`deps.memoryConsolidation
+ * !== undefined`),不是在这里写一个常量 —— S-399 把两席接上之后,本门**自动**从「恒拒」变成「阀门开着
+ * 就放行」,没有人需要记得回来改一个数。
+ *
+ * 🔴 **core 的拒绝谓词是两个析取项,本门只覆盖第一个**(对抗复审 F5 [low],验真后如实登记):
+ * core d.ts 逐字「`true` with nothing to run (**no `RunnerDeps.memoryConsolidation`, or no resolvable
+ * driver model seat**), or a non-boolean, is refused at prepare」。第二项(模型席解不出)本门不判,
+ * 而这在本仓**结构上不可达**:两席是**同一只已解析座**一起写上去的(`boot/runner-deps.ts` 的
+ * `ctx.consolidationSeat` 那一段)——座解析不出来时 {@link resolveConsolidationDriverSeat} 早在
+ * D1 那道门上就**拒启**了,轮不到这里。哪天有人把两席拆开各走各的路,这条「不可达」就失效,那时
+ * 本门要补第二项(core 侧的判据是 `consolidationSeatResolvable`,**不从包根导出**,届时要么向 core
+ * 要导出,要么在本层复现 —— 这一句留在这里就是为了那一天不必重新推一遍)。
+ *
+ * 未武装(`undefined` / `false`)⇒ 整条门不判。
+ */
+export declare function assertAutoConsolidationWirable(input: {
+    /** 部署席的三态读数(`config.memoryConsolidationDriver.autoRunOnRecommendation`)。 */
+    armed: boolean | undefined;
+    /** 铸好的 `RunnerDeps` 上**真的**有整理席吗(`deps.memoryConsolidation !== undefined`)。 */
+    memoryConsolidationWired: boolean;
+}): void;
 /** 两个 admin 口消费的窄能力面(`ServiceDeps.memoryConsolidation` 的实参来源)。 */
 export interface MemoryConsolidationFaces {
     /** D3 的座位自证(投影用;boot 期解析一次,restart-to-apply)。 */

package/dist/boot/memory-consolidation.js

@@ -107,6 +107,20 @@ export function buildStopDetailAudit(input) {
         untrustedDetail: redactSecrets(input.stopDetail).slice(0, STOP_DETAIL_LOG_MAX),
     };
 }
+export function assertAutoConsolidationWirable(input) {
+    if (input.armed !== true)
+        return;
+    if (input.memoryConsolidationWired)
+        return;
+    throw new Error(`MEMORY_AUTO_CONSOLIDATION=on arms automatic memory consolidation (a whole-library fold after every task that ` +
+        `recommended one — memory content EGRESSES to the configured consolidation model), but this deployment wires NO ` +
+        `engine-side consolidation seat (RunnerDeps.memoryConsolidation). The engine refuses that combination at EVERY ` +
+        `prepare (config.auto_consolidation), so this worker would boot fine and then fail every single task. ` +
+        `The engine-side seats are wired IFF MEMORY_CONSOLIDATION_DRIVER=on and a memory engine is wired — so either ` +
+        `set MEMORY_CONSOLIDATION_DRIVER=on (which also mounts the manual valve, and note that BOTH knobs then bill ` +
+        `whole-library model calls), or set MEMORY_AUTO_CONSOLIDATION=off (unsetting it is NOT the same: the engine's ` +
+        `named default is ON as of core 7.21.1).`);
+}
 export function createMemoryConsolidationFaces(store, input) {
     const engine = new MemoryEngine({
         backend: store.backend,

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

@@ -17,6 +17,7 @@ import type { ElicitationCoordinator } from "../elicitation.js";
 import { FleetEventBus } from "../fleet/fleet-bus.js";
 import type { Logger } from "../observability/logger.js";
 import type { Metrics } from "../observability/metrics.js";
+import { type ConsolidationDriverSeat } from "./memory-consolidation.js";
 import { WorkflowAgentRegistry } from "../orchestration/workflow-agent-steer.js";
 import { type WorkflowCompletionInbox } from "../orchestration/workflow-completion-inbox.js";
 import { type EngineNoticeRouter } from "../trace/engine-notice-wire.js";
@@ -148,6 +149,16 @@ export interface RunnerDepsCtx {
         backend: MemoryBackend;
         root: string;
     } | undefined;
+    /**
+     * S-399(core 7.21.1)—— 记忆整理的**已解析座**(`boot/memory-consolidation.ts` 的
+     * `resolveConsolidationDriverSeat` 产物),在场 **iff** `MEMORY_CONSOLIDATION_DRIVER=on` 且记忆引擎接了线。
+     *
+     * 🔴 **一座两用,不是两次装配**:同一只座同时喂 admin 阀门的操作面引擎与这里的引擎面两席
+     * (`RunnerDeps.memoryConsolidation` + `memoryConsolidationDriver`)。第二次解析会让「谁在花钱」
+     * 在两条腿上各答一遍,而座是 boot 期定的(restart-to-apply,理由在该模块顶注)。
+     * 缺席 ⇒ 两席都**不写键** ⇒ 引擎那半场对 7.20.x 逐字节不变。
+     */
+    consolidationSeat: ConsolidationDriverSeat | undefined;
     /** [ref]②([ref] §2.1b,core 7.0.2 [ref] 件2)/ S-215:会话 capture opt-out 记录的**按平面取用源**
      *  (`backend.sessionCaptureRecords()`,main.ts 取**一次**、与四只 operator 面引擎同一只源 —— 全站同批
      *  注入律,机器钉 = test/memory-capture-optout-lane.test.ts ②)。在场 ⇒ `capture:"off"` 声明与中途翻转

package/dist/boot/runner-deps.js

@@ -3,6 +3,7 @@ import { join } from "node:path";
 import { listCollabWorkflows, resolveCollabWorkflow } from "../capabilities/collab-workflows.js";
 import { fleetBackgroundChildPublisher, FleetEventBus } from "../fleet/fleet-bus.js";
 import { createMemoryEngineIncidentSink } from "../memory-incident-sink.js";
+import { assertAutoConsolidationWirable } from "./memory-consolidation.js";
 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";
@@ -274,9 +275,23 @@ export function createRunnerDeps(ctx) {
                 });
                 return;
             }
+            metrics.inc("runner_error_total", { phase: ctx.phase });
             logger.error("runner_error", { phase: ctx.phase, sessionId: ctx.sessionId, err: String(err) });
         },
+        ...(ctx.consolidationSeat !== undefined
+            ? {
+                memoryConsolidation: {},
+                memoryConsolidationDriver: { chat: ctx.consolidationSeat.options.chat, model: ctx.consolidationSeat.options.model },
+            }
+            : {}),
+        ...(config.memoryConsolidationDriver.autoRunOnRecommendation !== undefined
+            ? { autoRunOnRecommendation: config.memoryConsolidationDriver.autoRunOnRecommendation }
+            : {}),
     };
+    assertAutoConsolidationWirable({
+        armed: config.memoryConsolidationDriver.autoRunOnRecommendation,
+        memoryConsolidationWired: runnerDeps.memoryConsolidation !== undefined,
+    });
     return runnerDeps;
 }
 //# sourceMappingURL=runner-deps.js.map

package/dist/boot/stage-06-runners.js

@@ -62,15 +62,18 @@ export function runStage06(ctx) {
         memoryEngineBackend: config.memoryEngineBackend,
         ...(config.memoryProvenance !== undefined ? { provenance: config.memoryProvenance } : {}),
     });
-    const memoryConsolidationFaces = config.memoryConsolidationDriver.enabled && memoryEngine
+    const consolidationSeat = config.memoryConsolidationDriver.enabled && memoryEngine
+        ? resolveConsolidationDriverSeat({
+            brain,
+            models: config.models,
+            tiers: config.tiers,
+            roles: config.roles,
+            getApiKeyAndHeaders: createPerModelAuthSeat(() => configCenter.getKeyResolver()),
+        })
+        : undefined;
+    const memoryConsolidationFaces = consolidationSeat && memoryEngine
         ? createMemoryConsolidationFaces(memoryEngine, {
-            seat: resolveConsolidationDriverSeat({
-                brain,
-                models: config.models,
-                tiers: config.tiers,
-                roles: config.roles,
-                getApiKeyAndHeaders: createPerModelAuthSeat(() => configCenter.getKeyResolver()),
-            }),
+            seat: consolidationSeat,
             scopes: config.memoryConsolidationDriver.scopes,
             ...(config.memoryProvenance !== undefined ? { provenance: config.memoryProvenance } : {}),
             onIncident: (err) => logger.warn("memory_consolidation_incident", { code: err.code ?? null, detail: err.message }),
@@ -92,6 +95,7 @@ export function runStage06(ctx) {
             model: memoryConsolidationFaces.model,
             scopes: memoryConsolidationFaces.scopes,
             periodic: false,
+            autoRunOnRecommendation: config.memoryConsolidationDriver.autoRunOnRecommendation ?? "engine-default(on)",
         });
     }
     const governanceSeams = createGovernanceSeams({
@@ -108,6 +112,7 @@ export function runStage06(ctx) {
     const workflowModelAllowlistSnapshot = workflowModelAllowlistFor(config) ?? [];
     const sessionShellGateRegistry = createSessionShellGateRegistry();
     const runnerDeps = createRunnerDeps({
+        consolidationSeat,
         hands: commitHands,
         mcpRevocations,
         sessionShellGateExplicitlyOff: sessionShellGateRegistry.explicitlyOff,

package/dist/config-catalog.js

@@ -213,6 +213,7 @@ export const CONFIG_CATALOG = [
     r("MCP_ELICITATION_MAX_TOTAL", "approval", "number", "elicitation 每 run 总量帽", { derivedDefaultNote: "缺席 ⇒ core 出厂窗" }),
     r("MCP_ELICITATION_MIN_INTERVAL_MS", "approval", "number", "elicitation per-server 最小间隔(ms)", { derivedDefaultNote: "缺席 ⇒ core 出厂窗" }),
     r("MCP_ELICITATION_TTL_MS", "approval", "number", "elicitation 无人应答释放窗(ms)", { derivedDefaultNote: "缺席 ⇒ core 出厂窗" }),
+    r("MEMORY_AUTO_CONSOLIDATION", "memory", "enum", "记忆自动整理部署席(on=每个建议任务后整库整理跑,记忆内容自动外流到整理模型;off=显式关,胜过引擎缺省;未设=读引擎具名缺省)", { enumValues: ["on", "off"], derivedDefaultNote: "缺席 ⇒ 引擎具名缺省(**本版装的引擎是开**)——不配不等于关;前置=MEMORY_CONSOLIDATION_DRIVER=on", danger: SEC, resolve: (c) => c.memoryConsolidationDriver.autoRunOnRecommendation, booleanEnum: { true: "on", false: "off" } }),
     r("MEMORY_CAPTURE_POLICY", "memory", "enum", "记忆 capture 姿态(open=声明按面值;governed=按 per-principal verdict;capture-required=恒采)", { enumValues: ["open", "governed", "capture-required"], staticDefault: "open", danger: SEC, configKey: "memoryCapturePolicy" }),
     r("MEMORY_CONSOLIDATION_DRIVER", "memory", "enum", "记忆折叠阀门(off=零装配零探针,两 admin 口 404 族)", { enumValues: ["on", "off"], staticDefault: "off", danger: BILL, resolve: (c) => c.memoryConsolidationDriver.enabled, booleanEnum: { true: "on", false: "off" } }),
     r("MEMORY_CONSOLIDATION_INTERVAL_SEC", "memory", "number", "折叠周期腿节律(秒;本 build 任何正值拒启 —— 周期腿未落地,恒 0)", { staticDefault: "0" }),

package/dist/config-types.d.ts

@@ -140,6 +140,32 @@ export interface MemoryConsolidationDriverConfig {
      *  `src/memory-operator-faces.ts` 的 `erasureEnvelopeRefusal` 头注),在本层拿它当白名单就是**发明
      *  第二套授权语义**。显式传的 scope 照跑,表只管缺省。 */
     scopes: readonly string[];
+    /**
+     * S-362 / core 7.21.0 [ref] —— **`RunnerDeps.autoRunOnRecommendation` 的部署席**
+     * (env `MEMORY_AUTO_CONSOLIDATION=on|off`;**缺席 = 不写那个键**,由 core 的具名缺省
+     * `AUTO_RUN_ON_RECOMMENDATION_DEFAULT` 作答)。
+     *
+     * 🔴 **三态,不是布尔**,而且三态各有各的意思 —— 折成布尔会当场丢掉本旋钮存在的**唯一**理由:
+     *  · `undefined`(env 未设)= 不写 `RunnerDeps` 那个键 ⇒ 读 core 的具名缺省。core 7.21.0 发的是
+     *    `false`,而 clay [ref] 已裁**缺省开**、core 7.21.1 翻常量 —— 所以这一格的取值**会随提货漂**,
+     *    这正是它该有的样子(缺省的属主在 core)。
+     *  · `false`(`MEMORY_AUTO_CONSOLIDATION=off`)= **显式关,胜过缺省**。这是本旋钮的**关闭口**:
+     *    一台不愿意让记忆内容自动外流的部署,靠它在 core 把缺省翻开之后仍然保持关闭。
+     *  · `true`(`=on`)= 武装。**武装是一条出口决定,不是性能旋钮**:每个建议任务之后会有一次整库整理跑,
+     *    记忆内容自动外流到配置的整理模型 —— 设它之前请读 `boot/memory-consolidation.ts` 的 EGRESS 段。
+     *
+     * ⚠️ **前置 = `MEMORY_CONSOLIDATION_DRIVER=on`**(且记忆引擎接了线)。阀门开着 ⇒ 引擎那半场的整理两席
+     * (`RunnerDeps.memoryConsolidation` + `memoryConsolidationDriver`)由**同一只已解析座**接上
+     * (S-399,`boot/runner-deps.ts` 的 `ctx.consolidationSeat` 那一段)⇒ 本旋钮真的生效;阀门关着 ⇒ 两席
+     * 一个键都不写,而 core 对「武装但没接整理席」的处置是**每一次 prepare 都抛** `config.auto_consolidation`
+     * —— 那会买到一台**启动成功、每个任务都死**的机器,所以本仓把那一拒提前到启动期响亮拒
+     * (`assertAutoConsolidationWirable`,读的是刚铸出来的那只 deps 而不是一个手抄的布尔),与
+     * `MEMORY_CONSOLIDATION_DRIVER` 的 D1「安全/成本控件不得半开」同一条。
+     * 🔴 **本段自 S-399 改判**:S-362 那一批这里写的是「本 build 上 `on` 一定拒启(本仓没接整理席)」——
+     * 同一批的后半场把两席接上之后,那句话成了谎。旧世界断言留在树上比欠账更危险(7.81.0 整批的教训),
+     * 所以真相变了就地改,不留「将来某一版」的口气。
+     */
+    autoRunOnRecommendation?: boolean;
 }
 /** A sema-registry MCP server resolved to a core spec (env-NAME refs already → real values) plus the
  *  scenarios it applies to (empty = all). `resolveSpec` filters by scenario and passes `spec` to core. */

package/dist/config.js

@@ -1349,6 +1349,14 @@ function parseMemoryConsolidationDriver() {
             `spellings to preserve, unlike MEMORY_ENGINE's two-family word table.`);
     }
     const enabled = word === "on";
+    const autoWord = requireNonBlank("MEMORY_AUTO_CONSOLIDATION", process.env.MEMORY_AUTO_CONSOLIDATION);
+    if (autoWord !== undefined && autoWord !== "on" && autoWord !== "off") {
+        throw new Error(`MEMORY_AUTO_CONSOLIDATION must be exactly "on" or "off", got ${JSON.stringify(autoWord)} — this knob decides whether memory content ` +
+            `EGRESSES to the consolidation model automatically after every recommending task. A misspelled word read as "unset" would hand the ` +
+            `decision back to the engine's named default (which core is flipping to ON), so an operator who believes they turned it off would be ` +
+            `exporting their users' memory. UNSET it to take the engine default, or spell it exactly.`);
+    }
+    const autoRunOnRecommendation = autoWord === undefined ? undefined : autoWord === "on";
     let intervalSec = 0;
     const intervalRaw = requireNonBlank("MEMORY_CONSOLIDATION_INTERVAL_SEC", process.env.MEMORY_CONSOLIDATION_INTERVAL_SEC);
     if (intervalRaw !== undefined) {
@@ -1377,7 +1385,7 @@ function parseMemoryConsolidationDriver() {
             `the consolidation valve is OFF, so neither knob reaches anything (the two admin endpoints are not even mounted). ` +
             `Set MEMORY_CONSOLIDATION_DRIVER=on, or unset the other two.`);
     }
-    return { enabled, intervalSec, scopes };
+    return { enabled, intervalSec, scopes, ...(autoRunOnRecommendation !== undefined ? { autoRunOnRecommendation } : {}) };
 }
 function parseMemoryDomain(ctx) {
     const { requirePrincipal } = ctx;

package/dist/observability/metrics.js

@@ -229,6 +229,7 @@ export function createMetrics() {
     m.histogram("plan_cache_qsig", "Significant-token count of task objectives (qSig length)", [1, 2, 3, 5, 10, 20]);
     m.counter("memory_consolidation_ops_total", "Memory consolidation store ops (1.62 B-full), by op (update/delete)");
     m.counter("mcp_server_unavailable_total", "MCP servers skipped fail-open at task start (1.68), unreachable/misconfigured");
+    m.counter("runner_error_total", "RunnerDeps.onError frames that no phase arm claimed, by core phase (hook / compaction / interrupt-reconcile / suggestions)");
     m.counter("a2a_peer_unavailable_total", "A2A peers skipped at task start (DESIGN-269 client leg): card unreachable / spec unusable");
     m.counter("a2a_serve_rpc_total", "A2A server-as-peer JSON-RPC calls by method and outcome (DESIGN-269 车2)");
     m.counter("a2a_serve_rejected_total", "A2A server-as-peer requests refused before reaching a method handler, by reason (DESIGN-269 车2)");

package/dist/plugins/posix-shell-fs.d.ts

@@ -1,4 +1,4 @@
-import { FileError, type ExecutionError, type RemoteExecutionError, type FileInfo, type Result } from "@sema-agent/core";
+import { FileError, type ExecutionError, type RemoteExecutionError, type FileInfo, type Result, type SymlinkChain } from "@sema-agent/core";
 export interface ShellRunResult {
     stdout: string;
     stderr: string;
@@ -14,6 +14,7 @@ export interface PosixShellFsDeps {
 }
 export interface PosixShellFs {
     readLink(p: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
+    canonicalChain(p: string, abortSignal?: AbortSignal): Promise<Result<SymlinkChain, FileError>>;
     canonicalPath(p: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
     statFileInfo(p: string, abortSignal?: AbortSignal): Promise<Result<FileInfo, FileError>>;
     listDir(p: string, abortSignal?: AbortSignal): Promise<Result<FileInfo[], FileError>>;

package/dist/plugins/posix-shell-fs.js

@@ -1,6 +1,6 @@
 import path from "node:path";
 import { FileError, } from "@sema-agent/core";
-import { shellQuote, kindFromMode } from "./remote-shell.js";
+import { runSymlinkChain, shellQuote, kindFromMode } from "./remote-shell.js";
 import { classifyFsStderr, fileErrorFromExec } from "./remote-env-file-error.js";
 const ok = (value) => ({ ok: true, value });
 export function createPosixShellFs(deps) {
@@ -22,6 +22,9 @@ export function createPosixShellFs(deps) {
                 return { ok: false, error: classifyFsStderr(r.value.stderr, abs, "not_found") };
             return ok(r.value.stdout.trim());
         },
+        async canonicalChain(p, abortSignal) {
+            return runSymlinkChain(resolve(p), (cmd) => run(cmd, abortSignal));
+        },
         async canonicalPath(p, abortSignal) {
             const abs = resolve(p);
             const r = await run(`realpath -- ${shellQuote(abs)}`, abortSignal);

package/dist/plugins/remote-env-adb.d.ts

@@ -1,5 +1,5 @@
 import { spawn } from "node:child_process";
-import { FileError, ExecutionError, RemoteExecutionError, type ExecutionEnv, type RemoteExecutionEnv, type WorkspaceHandle, type FileInfo, type Result, type OutputChunk, type ExecStreamOptions, type RemoteConnectConfig, type SnapshotId, type SessionToken, type VmLifecycleOptions, type ExecutionEnvFactory } from "@sema-agent/core";
+import { FileError, ExecutionError, RemoteExecutionError, type ExecutionEnv, type RemoteExecutionEnv, type WorkspaceHandle, type FileInfo, type Result, type SymlinkChain, type OutputChunk, type ExecStreamOptions, type RemoteConnectConfig, type SnapshotId, type SessionToken, type VmLifecycleOptions, type ExecutionEnvFactory } from "@sema-agent/core";
 type ExecOpts = Parameters<ExecutionEnv["exec"]>[1];
 export interface AdbEnvConfig {
     /** Device serial or `host:port` (TCP). `host:port` triggers `adb connect` on connect()/reconnect(). */
@@ -139,6 +139,10 @@ export declare class RemoteAdbExecutionEnv implements RemoteExecutionEnv {
     fileInfo(p: string, abortSignal?: AbortSignal): Promise<Result<FileInfo, FileError>>;
     listDir(p: string, abortSignal?: AbortSignal): Promise<Result<FileInfo[], FileError>>;
     readLink(p: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
+    /** S-362 / core 7.21.0 [ref] —— **实现**(表态:本腿实现 `canonicalChain`)。一次往返里的一个 `readlink`
+     *  循环(上限 64、只锚不折、遇环即止),脚本与读法的单一属主在 `remote-shell.ts`,四条 shell 腿共用同一份。
+     *  缺席读法用不上(本腿在场);`ok:false` 由 core 读作「这一次没有跳」,永不是拒绝。 */
+    canonicalChain(p: string, abortSignal?: AbortSignal): Promise<Result<SymlinkChain, FileError>>;
     canonicalPath(p: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
     exists(p: string, abortSignal?: AbortSignal): Promise<Result<boolean, FileError>>;
     createDir(p: string, options?: {

package/dist/plugins/remote-env-adb.js

@@ -348,6 +348,9 @@ export class RemoteAdbExecutionEnv {
     async readLink(p, abortSignal) {
         return this.posixFs.readLink(p, abortSignal);
     }
+    async canonicalChain(p, abortSignal) {
+        return this.posixFs.canonicalChain(p, abortSignal);
+    }
     async canonicalPath(p, abortSignal) {
         return this.posixFs.canonicalPath(p, abortSignal);
     }

package/dist/plugins/remote-env-e2b.d.ts

@@ -20,7 +20,7 @@
  * iterator MAY throw `RemoteExecutionError` mid-stream before an `exit` chunk (seam contract, OutputChunk).
  */
 import { Sandbox, type SandboxOpts, type SandboxConnectOpts } from "e2b";
-import { FileError, ExecutionError, RemoteExecutionError, type ExecutionEnv, type RemoteExecutionEnv, type WorkspaceHandle, type FileInfo, type Result, type OutputChunk, type ExecStreamOptions, type RemoteConnectConfig, type SnapshotId, type SessionToken, type ExecutionEnvFactory, type VmLifecycleOptions, type BackgroundShellCapability, type BackgroundShellId, type BackgroundShellError, type BackgroundSpawnOptions, type BackgroundPoll } from "@sema-agent/core";
+import { FileError, ExecutionError, RemoteExecutionError, type ExecutionEnv, type RemoteExecutionEnv, type WorkspaceHandle, type FileInfo, type Result, type SymlinkChain, type OutputChunk, type ExecStreamOptions, type RemoteConnectConfig, type SnapshotId, type SessionToken, type ExecutionEnvFactory, type VmLifecycleOptions, type BackgroundShellCapability, type BackgroundShellId, type BackgroundShellError, type BackgroundSpawnOptions, type BackgroundPoll } from "@sema-agent/core";
 /** Options accepted by `ExecutionEnv.exec` (core does not re-export the type; derive it from the seam). */
 type ExecOpts = Parameters<ExecutionEnv["exec"]>[1];
 /** Minimal optional observability hooks (kept structural so the adapter stays standalone-testable). */
@@ -250,6 +250,13 @@ export declare class RemoteContainerExecutionEnv implements RemoteExecutionEnv,
      *  缺它 ⇒ 合法的悬空链接让整个工具调用失败。必须返回**原始链接目标**(`readlink` 不带 `-f`)。
      *  本腿的文件面也走 `exec`(与 canonicalPath 同通道),所以实现方式与 shell 腿一致。 */
     readLink(p: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
+    /** S-362 / core 7.21.0 [ref] —— **实现**(表态:本腿实现 `canonicalChain`)。本腿的文件面走原生 SDK 的
+     *  `exec`([ref] B6 的既有裁决:host 与 e2b 是原生 API 腿,**不并**进 `posix-shell-fs` 基座),但
+     *  「链怎么走、怎么读」与四条 shell 腿**是同一份**:脚本与读法的单一属主在 `remote-shell.ts`,这里只多一行
+     *  传输。一次往返、上限 64、只锚不折、遇环即止;`ok:false` 由 core 读作「这一次没有跳」,永不是拒绝。
+     *  🔴 exit≠0 归 `unknown` 而不是 `not_found`(与本腿 `readLink` 那一格刻意分家,同 `posix-shell-fs` 的理由):
+     *  「叶不是软链」与「叶不存在」在这条命令上都是 exit 0 + 空 stdout,所以 exit≠0 一定不是「文件不在」。 */
+    canonicalChain(p: string, abortSignal?: AbortSignal): Promise<Result<SymlinkChain, FileError>>;
     canonicalPath(p: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
     exists(p: string, abortSignal?: AbortSignal): Promise<Result<boolean, FileError>>;
     createDir(p: string, options?: {

package/dist/plugins/remote-env-e2b.js

@@ -2,7 +2,7 @@ import path from "node:path";
 import { Sandbox, CommandExitError, FileType } from "e2b";
 import { FileError, ExecutionError, RemoteExecutionError, RollingTailBuffer, markTruncated, } from "@sema-agent/core";
 import { fileErrorFromExec } from "./remote-env-file-error.js";
-import { numEnvOr, shellQuote } from "./remote-shell.js";
+import { numEnvOr, runSymlinkChain, shellQuote } from "./remote-shell.js";
 import { BackgroundShellManager } from "./background-shell-support.js";
 const PROVIDER = "e2b";
 const DEFAULT_MOUNT_PATH = "/home/user";
@@ -692,6 +692,9 @@ export class RemoteContainerExecutionEnv {
             return { ok: false, error: new FileError("not_found", r.value.stderr.trim() || `readlink failed for ${abs}`, abs) };
         return ok(r.value.stdout.trim());
     }
+    async canonicalChain(p, abortSignal) {
+        return runSymlinkChain(this.resolve(p), (cmd) => this.exec(cmd, { abortSignal }));
+    }
     async canonicalPath(p, abortSignal) {
         const abs = this.resolve(p);
         const r = await this.exec(`realpath -- ${shellQuote(abs)}`, { abortSignal });

package/dist/plugins/remote-env-host.d.ts

@@ -1,4 +1,4 @@
-import { FileError, ExecutionError, RemoteExecutionError, SchedulerError, type SchedulerCapability, type ScheduledIntent, type SchedulerContext, type ScheduledTaskId, type ScheduledTaskSummary, type ExecutionEnv, type RemoteExecutionEnv, type WorkspaceHandle, type FileInfo, type Result, type OutputChunk, type ExecStreamOptions, type RemoteConnectConfig, type SnapshotId, type SessionToken, type VmLifecycleOptions, type ExecutionEnvFactory, BackgroundShellError, type BackgroundShellCapability, type BackgroundShellId, type BackgroundPoll, type BackgroundSpawnOptions } from "@sema-agent/core";
+import { FileError, ExecutionError, RemoteExecutionError, SchedulerError, type SchedulerCapability, type ScheduledIntent, type SchedulerContext, type ScheduledTaskId, type ScheduledTaskSummary, type ExecutionEnv, type RemoteExecutionEnv, type WorkspaceHandle, type FileInfo, type Result, type SymlinkChain, type OutputChunk, type ExecStreamOptions, type RemoteConnectConfig, type SnapshotId, type SessionToken, type VmLifecycleOptions, type ExecutionEnvFactory, BackgroundShellError, type BackgroundShellCapability, type BackgroundShellId, type BackgroundPoll, type BackgroundSpawnOptions } from "@sema-agent/core";
 /** Options accepted by `ExecutionEnv.exec` (core does not re-export the type; derive it from the seam). */
 type ExecOpts = Parameters<ExecutionEnv["exec"]>[1];
 /** Construction config for {@link RemoteHostExecutionEnv}. */
@@ -216,6 +216,20 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
     listDir(p: string, abortSignal?: AbortSignal): Promise<Result<FileInfo[], FileError>>;
     canonicalPath(p: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
     readLink(p: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
+    /**
+     * S-362 / core 7.21.0 [ref] —— **实现**(表态:本腿实现 `canonicalChain`)。host 腿是 node:fs 腿,所以按
+     * 提货单 [ref] @server 五适配器段的第一行,与 core 的 `NodeExecutionEnv.canonicalChain` **同形**:对整条
+     * 拼法 `readlink`,再对每一跳 `readlink`,**上限 64**、**只锚不折**、**遇环即止**;win32 宿主上跳到共享
+     * (UNC)时**记下该跳并停止探测**(不碰网络,CC `vr` 对网络拼法只给拼法)。
+     *
+     * 🔴 **不复用 core 的实现而是同形重写**:`NodeExecutionEnv` 是 core 的内部类,包根不导出它的这只方法;
+     * 而本腿的每一次读都必须先过 {@link fsReady}(2026-07-25 全族统一:拆除之后只读面不得与写面自相矛盾),
+     * 那道门在 core 的实现里不存在。同形的判据钉在 `test/remote-env-canonical-chain.test.ts`。
+     *
+     * 链尽的三种 errno(`EINVAL` 不是软链 / `ENOENT` 不存在 / `ENOTDIR`)⇒ `ok` + 到此为止的跳;其余 errno
+     * (`EACCES` …)⇒ `ok:false`(core 读作「这一次没有跳」,**永不是拒绝**)。非链接的叶答 `[]`。
+     */
+    canonicalChain(p: string, abortSignal?: AbortSignal): Promise<Result<SymlinkChain, FileError>>;
     exists(p: string, abortSignal?: AbortSignal): Promise<Result<boolean, FileError>>;
     createDir(p: string, options?: {
         recursive?: boolean;

package/dist/plugins/remote-env-host.js

@@ -5,7 +5,7 @@ import fs from "node:fs/promises";
 import { randomBytes } from "node:crypto";
 import { openSync, closeSync, readSync, statSync, truncateSync, unlinkSync, mkdirSync, rmdirSync, mkdtempSync, existsSync, realpathSync, accessSync, constants as FS_CONST } from "node:fs";
 import { StringDecoder } from "node:string_decoder";
-import { armPipeDestroyGrace, numEnvOr } from "./remote-shell.js";
+import { armPipeDestroyGrace, numEnvOr, SYMLINK_CHAIN_MAX_HOPS } from "./remote-shell.js";
 import { hostBackgroundShellEnabled, hostExecSpoolEnabled } from "../config.js";
 import { resolveHostShell, hostShell, spawnGroupOptions, killTreeHard, killTreeSoft, collapseWin32EnvKeys } from "./host-platform.js";
 import { BackgroundShellManager, seedMemStream, feedMemStream, drainMemStream } from "./background-shell-support.js";
@@ -22,6 +22,7 @@ const HOST_BG_FILE_CAP = numEnvOr("HOST_BG_FILE_CAP", 64 * 1024 * 1024, HOST_BG_
 const HOST_BG_KILL_GRACE_MS = numEnvOr("HOST_BG_KILL_GRACE_MS", 1000, 0);
 const HOST_BG_MEM_CAP = numEnvOr("HOST_BG_MEM_CAP", 8 * 1024 * 1024, 64 * 1024);
 const ok = (value) => ({ ok: true, value });
+const UNC_SPELLING = /^[\\/]{2}[^\\/]+[\\/]+[^\\/]/;
 const unsupported = (op) => ({
     ok: false,
     error: new RemoteExecutionError("unsupported", `${op} is not supported on a host target (the operator's own machine — no container boundary, not snapshotable; capabilities.suspendable=false)`),
@@ -1006,6 +1007,41 @@ export class RemoteHostExecutionEnv {
             return { ok: false, error: this.fileError(e, abs, abortSignal) };
         }
     }
+    async canonicalChain(p, abortSignal) {
+        const ready = await this.fsReady(p);
+        if (!ready.ok)
+            return ready;
+        const hops = [];
+        const seen = new Set();
+        let cur = this.resolve(p);
+        for (let i = 0; i < SYMLINK_CHAIN_MAX_HOPS; i += 1) {
+            let target;
+            try {
+                target = await fs.readlink(cur);
+            }
+            catch (e) {
+                const fe = this.fileError(e, cur, abortSignal);
+                if (fe.code === "invalid" || fe.code === "not_found" || fe.code === "not_directory")
+                    break;
+                return { ok: false, error: fe };
+            }
+            let next;
+            if (path.isAbsolute(target))
+                next = target;
+            else {
+                const dir = path.dirname(cur);
+                next = dir.endsWith(path.sep) ? `${dir}${target}` : `${dir}${path.sep}${target}`;
+            }
+            if (seen.has(next))
+                break;
+            seen.add(next);
+            hops.push(next);
+            if (process.platform === "win32" && UNC_SPELLING.test(next))
+                break;
+            cur = next;
+        }
+        return ok({ hops });
+    }
     async exists(p, abortSignal) {
         const ready = await this.fsReady(p);
         if (!ready.ok)

package/dist/plugins/remote-env-k8s.d.ts

@@ -1,4 +1,4 @@
-import { FileError, ExecutionError, RemoteExecutionError, type ExecutionEnv, type RemoteExecutionEnv, type WorkspaceHandle, type FileInfo, type Result, type OutputChunk, type ExecStreamOptions, type RemoteConnectConfig, type SnapshotId, type SessionToken, type VmLifecycleOptions, type ExecutionEnvFactory, type BackgroundShellCapability, type BackgroundShellId, type BackgroundShellError, type BackgroundSpawnOptions, type BackgroundPoll } from "@sema-agent/core";
+import { FileError, ExecutionError, RemoteExecutionError, type ExecutionEnv, type RemoteExecutionEnv, type WorkspaceHandle, type FileInfo, type Result, type SymlinkChain, type OutputChunk, type ExecStreamOptions, type RemoteConnectConfig, type SnapshotId, type SessionToken, type VmLifecycleOptions, type ExecutionEnvFactory, type BackgroundShellCapability, type BackgroundShellId, type BackgroundShellError, type BackgroundSpawnOptions, type BackgroundPoll } from "@sema-agent/core";
 import type { PodSpecPatch } from "./k8s-exec-protocol.js";
 type ExecOpts = Parameters<ExecutionEnv["exec"]>[1];
 export { buildBgRunnerScript, buildBgLauncherScript, buildBgPollScript, buildBgKillScript, buildBgDisposeScript, buildDetachCapableExec, parseBgPollOutput, type ParsedBgPoll, } from "./k8s-bg-scripts.js";
@@ -310,6 +310,10 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
     fileInfo(p: string, abortSignal?: AbortSignal): Promise<Result<FileInfo, FileError>>;
     listDir(p: string, abortSignal?: AbortSignal): Promise<Result<FileInfo[], FileError>>;
     readLink(p: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
+    /** S-362 / core 7.21.0 [ref] —— **实现**(表态:本腿实现 `canonicalChain`)。一次往返里的一个 `readlink`
+     *  循环(上限 64、只锚不折、遇环即止),脚本与读法的单一属主在 `remote-shell.ts`,四条 shell 腿共用同一份。
+     *  缺席读法用不上(本腿在场);`ok:false` 由 core 读作「这一次没有跳」,永不是拒绝。 */
+    canonicalChain(p: string, abortSignal?: AbortSignal): Promise<Result<SymlinkChain, FileError>>;
     canonicalPath(p: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
     exists(p: string, abortSignal?: AbortSignal): Promise<Result<boolean, FileError>>;
     createDir(p: string, options?: {

package/dist/plugins/remote-env-k8s.js

@@ -919,6 +919,9 @@ export class RemoteK8sExecutionEnv {
     async readLink(p, abortSignal) {
         return this.posixFs.readLink(p, abortSignal);
     }
+    async canonicalChain(p, abortSignal) {
+        return this.posixFs.canonicalChain(p, abortSignal);
+    }
     async canonicalPath(p, abortSignal) {
         return this.posixFs.canonicalPath(p, abortSignal);
     }

package/dist/plugins/remote-env-local-docker.d.ts

@@ -1,5 +1,5 @@
 import { spawn } from "node:child_process";
-import { FileError, ExecutionError, RemoteExecutionError, type ExecutionEnv, type RemoteExecutionEnv, type WorkspaceHandle, type FileInfo, type Result, type OutputChunk, type ExecStreamOptions, type RemoteConnectConfig, type SnapshotId, type SessionToken, type VmLifecycleOptions, type ExecutionEnvFactory } from "@sema-agent/core";
+import { FileError, ExecutionError, RemoteExecutionError, type ExecutionEnv, type RemoteExecutionEnv, type WorkspaceHandle, type FileInfo, type Result, type SymlinkChain, type OutputChunk, type ExecStreamOptions, type RemoteConnectConfig, type SnapshotId, type SessionToken, type VmLifecycleOptions, type ExecutionEnvFactory } from "@sema-agent/core";
 /** Options accepted by `ExecutionEnv.exec` (core does not re-export the type; derive it from the seam). */
 type ExecOpts = Parameters<ExecutionEnv["exec"]>[1];
 /** Construction config for {@link RemoteLocalDockerExecutionEnv}. */
@@ -166,6 +166,10 @@ export declare class RemoteLocalDockerExecutionEnv implements RemoteExecutionEnv
     fileInfo(p: string, abortSignal?: AbortSignal): Promise<Result<FileInfo, FileError>>;
     listDir(p: string, abortSignal?: AbortSignal): Promise<Result<FileInfo[], FileError>>;
     readLink(p: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
+    /** S-362 / core 7.21.0 [ref] —— **实现**(表态:本腿实现 `canonicalChain`)。一次往返里的一个 `readlink`
+     *  循环(上限 64、只锚不折、遇环即止),脚本与读法的单一属主在 `remote-shell.ts`,四条 shell 腿共用同一份。
+     *  缺席读法用不上(本腿在场);`ok:false` 由 core 读作「这一次没有跳」,永不是拒绝。 */
+    canonicalChain(p: string, abortSignal?: AbortSignal): Promise<Result<SymlinkChain, FileError>>;
     canonicalPath(p: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
     exists(p: string, abortSignal?: AbortSignal): Promise<Result<boolean, FileError>>;
     createDir(p: string, options?: {

package/dist/plugins/remote-env-local-docker.js

@@ -406,6 +406,9 @@ export class RemoteLocalDockerExecutionEnv {
     async readLink(p, abortSignal) {
         return this.posixFs.readLink(p, abortSignal);
     }
+    async canonicalChain(p, abortSignal) {
+        return this.posixFs.canonicalChain(p, abortSignal);
+    }
     async canonicalPath(p, abortSignal) {
         return this.posixFs.canonicalPath(p, abortSignal);
     }

package/dist/plugins/remote-env-ssh.d.ts

@@ -1,5 +1,5 @@
 import { type SshHostKeyPolicy } from "../ssh-host-key.js";
-import { FileError, ExecutionError, RemoteExecutionError, type ExecutionEnv, type RemoteExecutionEnv, type WorkspaceHandle, type FileInfo, type Result, type OutputChunk, type ExecStreamOptions, type RemoteConnectConfig, type SnapshotId, type SessionToken, type VmLifecycleOptions, type ExecutionEnvFactory } from "@sema-agent/core";
+import { FileError, ExecutionError, RemoteExecutionError, type ExecutionEnv, type RemoteExecutionEnv, type WorkspaceHandle, type FileInfo, type Result, type SymlinkChain, type OutputChunk, type ExecStreamOptions, type RemoteConnectConfig, type SnapshotId, type SessionToken, type VmLifecycleOptions, type ExecutionEnvFactory } from "@sema-agent/core";
 type ExecOpts = Parameters<ExecutionEnv["exec"]>[1];
 export interface SshEnvConfig {
     host: string;
@@ -171,6 +171,10 @@ export declare class RemoteSshExecutionEnv implements RemoteExecutionEnv {
     private posixFsInst?;
     private get posixFs();
     readLink(p: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
+    /** S-362 / core 7.21.0 [ref] —— **实现**(表态:本腿实现 `canonicalChain`)。一次往返里的一个 `readlink`
+     *  循环(上限 64、只锚不折、遇环即止),脚本与读法的单一属主在 `remote-shell.ts`,四条 shell 腿共用同一份。
+     *  缺席读法用不上(本腿在场);`ok:false` 由 core 读作「这一次没有跳」,永不是拒绝。 */
+    canonicalChain(p: string, abortSignal?: AbortSignal): Promise<Result<SymlinkChain, FileError>>;
     canonicalPath(p: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
     exists(p: string, abortSignal?: AbortSignal): Promise<Result<boolean, FileError>>;
     createDir(p: string, options?: {

package/dist/plugins/remote-env-ssh.js

@@ -548,6 +548,9 @@ export class RemoteSshExecutionEnv {
     async readLink(p, abortSignal) {
         return this.posixFs.readLink(p, abortSignal);
     }
+    async canonicalChain(p, abortSignal) {
+        return this.posixFs.canonicalChain(p, abortSignal);
+    }
     async canonicalPath(p, abortSignal) {
         return this.posixFs.canonicalPath(p, abortSignal);
     }

package/dist/plugins/remote-shell.d.ts

@@ -2,7 +2,7 @@
  * Shared shell/path helpers for the SSH + ADB `RemoteExecutionEnv` adapters. Kept in ONE place so the
  * security-sensitive quoting can't drift between adapters (council design/#4, #5).
  */
-import type { FileInfo } from "@sema-agent/core";
+import type { ExecutionError, FileError, FileInfo, RemoteExecutionError, Result, SymlinkChain } from "@sema-agent/core";
 import type { ChildProcess } from "node:child_process";
 /**
  * D5 pipe-destroy grace (parity with core's vendored `EXEC_FORCE_SETTLE_GRACE_MS`, harness/env/nodejs.js):
@@ -32,4 +32,81 @@ export declare function drainNumEnvWarnings(): Array<{
     raw: string;
 }>;
 export declare function numEnvOr(name: string, def: number, min: number): number;
+export declare const SYMLINK_CHAIN_MAX_HOPS = 64;
+/**
+ * 一次往返走完叶 symlink 链的 POSIX sh 脚本(**纯数据**:返回一个命令串 ⇒ `build*`,CLAUDE.md 工厂律)。
+ *
+ * 🔴 `readlink` **缺失**必须与「不是软链」分开:两者在 shell 里都是 exit≠0,而 `|| break` 会把「工具不在」
+ *   静默读成「零跳」—— 那是安全轴上的静默兜底(链视图整条消失,判官少一个视图)。所以脚本**先探**一次
+ *   `command -v`,缺失时打一句 `readlink: not found` 到 stderr 并 exit 127 —— 那句话正好命中
+ *   {@link import("./remote-env-file-error.js").classifyFsStderr} 的**命令缺失护栏**(它把命令缺失归
+ *   `unknown` 而不是 `not_found`),于是调用方拿到的是 `ok:false`(core 读作「这一次没有跳」,永不是拒绝)
+ *   而不是一个伪造的空链。
+ *
+ * 🔴 **整条命令包在一个 `{ …; }` 里**,理由是**调用方会给它加前缀**:四条腿的 `withCwdEnv` 都拼
+ *   `cd <dir> && <命令>`(ssh `:760` / k8s `:1418` / adb `:578` / local-docker 同形)。这里连着犯过两次错,
+ *   两次都记下来,因为它们是**同一个坑的两面**:
+ *   · 写成 `command -v … || { …; }`:`||` 与前缀的 `&&` 结成一条链(`cd X && command -v … || { … }`),
+ *     **`cd` 失败时跑的是探测的失败臂** —— 报「readlink 不在」而真相是「那个目录没了」,运维去修一个没坏的东西;
+ *   · 改成独立语句 `if ! …; fi; c=…; while …`:前缀的 `&&` 只短路**那一条 `if`**,后面的循环照跑 ——
+ *     于是「`cd` 失败 ∧ readlink 缺失」这一格里,`|| break` 把工具缺失吞成零跳,脚本 **exit 0 + 空 stdout**,
+ *     调用方拿到一条**伪造的空链**。这正是探测本来要挡的那个静默兜底([ref] 轴),换了个入口回来了。
+ *   ⇒ 正解是**让整条命令只有一个退出状态**:包进 `{ …; }`,前缀的 `&&` 要么统治全部、要么全部不跑。
+ *     `cd` 失败 ⇒ 退出码来自 `cd` 自己、stderr 是它自己的话 ⇒ `ok:false`(core 读作「这一次没有跳」),
+ *     诚实且指向真因;`cd` 成功 ⇒ 探测与循环照旧。`{ }` 不是子 shell,里面的 `exit 127` 照样结束整条命令。
+ *
+ * 词法细节(逐条对着 core 的 Node 实现写,两边同形):绝对目标直接接上;相对目标用参数展开
+ * `${c%/*}` 取**当前这条链接**所在目录(不调 `dirname` —— toybox 的 `dirname` 不认 `--`,且这里零外部命令
+ * 更省一次 fork),根目录那一格(`${c%/*}` 为空)补 `/`。**全程不折叠 `..`**。
+ */
+export declare function buildSymlinkChainCommand(absPath: string): string;
+/**
+ * {@link buildSymlinkChainCommand} 的 stdout → `SymlinkChain.hops`。
+ *
+ * 三件事**只在这里**做一次(四条 shell 腿 + e2b 共读):
+ *  · **环即止** —— 出现重复跳时在**重复的那一跳之前**截断(CC `vr` 的 `d.has(u)` 同律)。
+ *    🔴 **一条如实登记的、与 core 参考实现的分歧(合并复审车GU 亲核两树,验真后**披露不修**)**:本族(六腿同形)
+ *    的 seen 表**从空开始**,而 core 的 `NodeExecutionEnv.canonicalChain` 用**被寻址的拼法**给它播种
+ *    (`new Set([resolved])`)。于是**环绕回起点**的那一类链上两边差一跳:`a -> b`、`b -> a`,问 `a`,本族答
+ *    `[b, a]`,core 答 `[b]`。**只在真有环时可观察**(无环链上 seen 永远碰不到起点,两边逐字节相同),而有环的
+ *    链上那次写本来就会以 `ELOOP` 失败。不修的两条理由:①方向是**多报一跳**(判官多一个视图 ⇒ 多问,从不
+ *    造成误放行),而改成与 core 同形是**摘掉**一个视图 —— 在 [ref] 轴上那是错的方向,要动得先有裁定;
+ *    ②那一跳是 `b` **真的写下的**目标,契约句「不重复被寻址的拼法」两种读法都讲得通(core 读作「起点不入表」,
+ *    本族读作「每条链接写下的目标都入表」),属**待 core 裁**的一格,不是本仓单方面能定的。
+ *    ⚠️ 故各腿头注里「与 core 同形 / 逐字节对得上」那句话的射程是**无环链**;有环的那一格以本段为准。
+ *    脚本侧不做:
+ *    POSIX sh 里维护一张 seen 表要么靠内嵌换行的 `case` 模式(易碎),要么另起一个进程;放在这里则
+ *    **一份实现**被四条腿与 e2b 共用,且与 host 腿的 Node 循环逐字节对得上。代价如实登记:链上真有环时,
+ *    远端在**那一次往返内**最多多跑到 64 次 `readlink`(有界,不是无界探测),而报出来的跳与 host 腿相同。
+ *  · **上限 64** —— 脚本已经封顶,这里再切一次是对**传输层**的不信任(答多了不当真),不是第二份判据。
+ *  · **逐行 trim** —— 与本族 `readLink` 的既有姿态**同一条**(基座头注:链接目标含换行是病态形,按 trim
+ *    处理,不假装支持)。残留如实写出来:目标拼法真带首尾空白时,trim 后的跳可能与真目标差几个字节 ——
+ *    方向上只会让一条跳**匹配不到**受保护行(少问,不是多放行),而终点判决(`canonicalPath`)完全不经本路。
+ */
+export declare function symlinkChainHopsFromStdout(stdout: string): string[];
+/** {@link runSymlinkChain} 的传输面 —— 各腿的 `exec` 收敛成的那一个形(与 `PosixShellFs` 基座的 `run` 同形)。 */
+export type ShellChainRun = (cmd: string) => Promise<Result<{
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}, ExecutionError | RemoteExecutionError>>;
+/**
+ * **shell 形 `canonicalChain` 的全部半场,一处**(对抗复审 F4 [low],验真后按类修)。
+ *
+ * 此前脚本与读法收在这里,而「怎么把它们接到传输上、exit≠0 怎么归码」在**两处**各写一遍:
+ * `posix-shell-fs.ts`(四条 shell 腿)与 `remote-env-e2b.ts`(原生 SDK 腿)。两份五行代码语义相同、
+ * 错误归类却各写各的,于是「e2b 与四条 shell 腿答得一样」只靠一句注释担保 —— 复审的换靶变异实测:
+ * 把 e2b 那五行改成 `return ok({ hops: [] })`,**全部钉照绿**。收成一只函数之后,那条担保是结构事实:
+ * 两边调的是同一个函数,分叉无处可生;基座上那一整套行为钉同时就是 e2b 的钉。
+ *
+ * 归码(两腿共用同一条,不再各写各的):
+ *  · 传输自己失败 ⇒ {@link fileErrorFromExec}(`aborted` 穿透,其余诚实降级 `unknown`);
+ *  · exit≠0 ⇒ {@link classifyFsStderr} 且 fallback 取 **`unknown` 而不是 `not_found`** —— 这条命令上
+ *    「叶不是软链」与「叶不存在」**都是 exit 0 + 空 stdout**(脚本里的 `|| break`),所以任何 exit≠0
+ *    都**不是**「这个文件不在」,而是解析器自己出了事(工具缺失 / cwd 没了 / 传输坏 / shell 拒)。
+ *    把它折成 `not_found` 会让运维去找一条根本没丢的路径。
+ *    ⚠️ 例外由 `classifyFsStderr` 自己认:`cd` 失败那一格的 stderr 里真带「No such file」,它按**那句话**
+ *    归 `not_found` —— 那时真的有一条路径没了(工作目录),所以那个码是对的。
+ */
+export declare function runSymlinkChain(absPath: string, run: ShellChainRun): Promise<Result<SymlinkChain, FileError>>;
 //# sourceMappingURL=remote-shell.d.ts.map

package/dist/plugins/remote-shell.js

@@ -1,3 +1,4 @@
+import { classifyFsStderr, fileErrorFromExec } from "./remote-env-file-error.js";
 export const EXEC_FORCE_SETTLE_GRACE_MS = 3000;
 export function armPipeDestroyGrace(child) {
     const t = setTimeout(() => {
@@ -36,4 +37,38 @@ export function numEnvOr(name, def, min) {
     }
     return Math.max(min, (Number.isFinite(n) ? n : 0) || def);
 }
+export const SYMLINK_CHAIN_MAX_HOPS = 64;
+export function buildSymlinkChainCommand(absPath) {
+    return (`{ if ! command -v readlink >/dev/null 2>&1; then printf 'readlink: not found\\n' >&2; exit 127; fi; ` +
+        `c=${shellQuote(absPath)}; n=0; ` +
+        `while [ "$n" -lt ${SYMLINK_CHAIN_MAX_HOPS} ]; do ` +
+        `t=$(readlink -- "$c") || break; ` +
+        `case "$t" in "") break ;; /*) c="$t" ;; ` +
+        `*) d="${"${c%/*}"}"; case "$d" in "") c="/$t" ;; */) c="$d$t" ;; *) c="$d/$t" ;; esac ;; esac; ` +
+        `printf '%s\\n' "$c"; n=$((n+1)); done; }`);
+}
+export function symlinkChainHopsFromStdout(stdout) {
+    const hops = [];
+    const seen = new Set();
+    for (const raw of stdout.split("\n")) {
+        const hop = raw.trim();
+        if (hop === "")
+            continue;
+        if (seen.has(hop))
+            break;
+        seen.add(hop);
+        hops.push(hop);
+        if (hops.length >= SYMLINK_CHAIN_MAX_HOPS)
+            break;
+    }
+    return hops;
+}
+export async function runSymlinkChain(absPath, run) {
+    const r = await run(buildSymlinkChainCommand(absPath));
+    if (!r.ok)
+        return { ok: false, error: fileErrorFromExec(r.error, absPath) };
+    if (r.value.exitCode !== 0)
+        return { ok: false, error: classifyFsStderr(r.value.stderr, absPath, "unknown") };
+    return { ok: true, value: { hops: symlinkChainHopsFromStdout(r.value.stdout) } };
+}
 //# sourceMappingURL=remote-shell.js.map

package/dist/trace/core-keyset-guard.d.ts

@@ -60,7 +60,7 @@ type MailboxAppendProjected = "from" | "content" | "sentAt" | "hopChain" | "peer
 type _GuardMailboxAppend = AssertAllKeysHandled<Exclude<keyof MailboxAppendMessage, MailboxAppendProjected>>;
 type _GuardMailboxAppendReverse = AssertAllKeysHandled<Exclude<MailboxAppendProjected, keyof MailboxAppendMessage>>;
 type WiringSectionProjected = "schemaVersion" | "leg" | "ask" | "question" | "interaction" | "elicit" | "parkLane" | "session" | "fleet" | "permissionRules" | "modelGate" | "autoMode" | "mcp" | "tools" | "hooks" | "lsp" | "writeProtection";
-type WiringSectionExcluded = "governance" | "configFingerprint";
+type WiringSectionExcluded = "governance" | "configFingerprint" | "autoConsolidation";
 type _GuardWiringSections = AssertAllKeysHandled<Exclude<keyof WiringManifest, WiringSectionProjected | WiringSectionExcluded>>;
 type _GuardWiringSectionsReverse = AssertAllKeysHandled<Exclude<WiringSectionProjected | WiringSectionExcluded, keyof WiringManifest>>;
 type WiringSection<K extends keyof WiringManifest> = NonNullable<WiringManifest[K]>;
@@ -103,6 +103,9 @@ type _GuardWiringRulesReverse = AssertAllKeysHandled<Exclude<WiringRulesHandled,
 type WiringWriteProtectionHandled = "targetView";
 type _GuardWiringWriteProtection = AssertAllKeysHandled<Exclude<keyof WiringSection<"writeProtection">, WiringWriteProtectionHandled>>;
 type _GuardWiringWriteProtectionReverse = AssertAllKeysHandled<Exclude<WiringWriteProtectionHandled, keyof WiringSection<"writeProtection">>>;
+type WiringAutoConsolidationHandled = "onRecommendation";
+type _GuardWiringAutoConsolidation = AssertAllKeysHandled<Exclude<keyof WiringSection<"autoConsolidation">, WiringAutoConsolidationHandled>>;
+type _GuardWiringAutoConsolidationReverse = AssertAllKeysHandled<Exclude<WiringAutoConsolidationHandled, keyof WiringSection<"autoConsolidation">>>;
 type WiringModelGateHandled = "class" | "removed" | "restore";
 type _GuardWiringModelGate = AssertAllKeysHandled<Exclude<keyof WiringSection<"modelGate">, WiringModelGateHandled>>;
 type _GuardWiringModelGateReverse = AssertAllKeysHandled<Exclude<WiringModelGateHandled, keyof WiringSection<"modelGate">>>;
@@ -185,6 +188,8 @@ export type CoreKeysetGuards = [
     _GuardWiringSections,
     _GuardWiringWriteProtection,
     _GuardWiringWriteProtectionReverse,
+    _GuardWiringAutoConsolidation,
+    _GuardWiringAutoConsolidationReverse,
     _GuardWiringSectionsReverse,
     _GuardWiringLeg,
     _GuardWiringLegReverse,

package/dist/trace/project.d.ts

@@ -604,6 +604,14 @@ export declare function workspaceChangedEventData(ev: {
  *    ⚠️ **缺席 = 第三态**:core 的段是 **present-iff 编译出了判官**,`writeProtectedPaths: []` 的部署
  *       整段缺席。缺席**绝不**折成 `"spelling-only"`(那是「判官在、但只认拼法」,完全不同的一件事),
  *       也不铸 `writeProtection: {}`。词出闭集同样**不**折进缺席,走 `dropProjectedFace` 留痕(见那里)。
+ *  · `autoConsolidation`(`{ onRecommendation: true }`;core 7.21.0 [ref],S-362 提货件)—— **裁:operator
+ *    受众,租户面剥**,所以它**不在本构造器里**,在 {@link wiringManifestOperatorEventData}。四条判据逐字在
+ *    `core-keyset-guard.ts` ⑥b 的 `WiringSectionExcluded` 那一行(与 `governance` / `configFingerprint`
+ *    同表同处,免得同一条裁定有两个写者)。一句话:它是**出口事实**(武装 = 每个建议任务之后整库记忆自动
+ *    外流到整理模型),与 governance 四布尔同族,而不是 `writeProtection` 那种「这条腿手里有什么」的自述;
+ *    并且它对调用方**本就不可观测**(整理跑在终端 harvest 之后、fire-and-forget、宿主侧),剥掉它不收走
+ *    任何能力 —— 这正是 `writeProtection` 判据①**不成立**的那一格。
+ *    ⚠️ **缺席 = 未武装**(core present-iff),不折 `false`、不读「未知」。
  * 未来 core 加一段而它没有 audience 标签时,**先在这里补一条裁定再决定挑不挑键** —— 段级完备性钉
  * (test/wiring-manifest-projection.test.ts)会在那一刻先把人拦下来 —— ⚠️ **但那条钉是夹具驱动的**:它只看
  * `deriveWiringManifest(EFFECTIVE_FACTS)` 真铸出来的段,facts 不带的可选段(147③ 的 `autoMode` 就是)它一格
@@ -662,6 +670,16 @@ export declare function wiringManifestEventData(ev: {
  *
  * governance **逐键挑**(禁 `{...governance}`):core 往这个段里加第五键时必须由人显式处置,而不是顺着
  * spread 裸上线 —— 这个段的每一键都是部署治理面,新键的默认待遇必须是「不发」。
+ *
+ * `autoConsolidation`(core 7.21.0 [ref],S-362)与 governance 同规:租户面剥、本面发(裁定四条判据在
+ * `core-keyset-guard.ts` ⑥b `WiringSectionExcluded`)。**present-iff 武装**:
+ *  · 整段缺席 ⇒ **未武装**,不铸键、不计数(正面事实,不是「未知」,更不是 `{onRecommendation:false}`);
+ *  · 在场且 `onRecommendation === true` ⇒ 逐字铸出(core 的在场形只有这一个,构造期门已拒掉「武装但跑不起来」);
+ *  · 在场但读不出那个形 ⇒ `dropProjectedFace` 留痕并整段缺席(与 `writeProtection` / `lsp` / `hooks` 同一条
+ *    族规:「在场但读不出 ⇒ 计一次并丢弃」;**不**自造第三态,词表/形的属主在 core)。
+ *    🔴 代价如实登记,与 `writeProtection` 那一格逐字同源:wire 上「读不出」与「真未武装」是**同一个形**,
+ *    分得开它们的只有 `server.trace.projection-input-malformed` 这只计数 —— 而这一格比那一格更该说清楚,
+ *    因为它读错的方向是**把一台正在外流记忆的部署渲染成没在外流**。故本段的读不出**必须**留痕,不许静默。
  */
 export declare function wiringManifestOperatorEventData(ev: {
     manifest?: unknown;

package/dist/trace/project.js

@@ -554,9 +554,20 @@ export function wiringManifestOperatorEventData(ev) {
         ...(bool(g.memoryAdmission) !== undefined ? { memoryAdmission: g.memoryAdmission } : {}),
         ...(bool(g.retention) !== undefined ? { retention: g.retention } : {}),
     };
+    const autoConsolidation = (() => {
+        if (m.autoConsolidation === undefined)
+            return undefined;
+        const seg = sec(m.autoConsolidation);
+        if (seg === undefined)
+            return dropProjectedFace("wiring_manifest.autoConsolidation is not an object");
+        if (bool(seg.onRecommendation) !== true)
+            return dropProjectedFace("wiring_manifest.autoConsolidation.onRecommendation is not literal true (core's only present form)");
+        return { onRecommendation: true };
+    })();
     return {
         ...tenant,
         ...(Object.keys(governance).length > 0 ? { governance } : {}),
+        ...(autoConsolidation !== undefined ? { autoConsolidation } : {}),
         ...(str(m.configFingerprint) !== undefined ? { configFingerprint: m.configFingerprint } : {}),
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/server",
-  "version": "7.81.0",
+  "version": "7.82.0",
   "description": "Sema Server — the server/API implementation layer for Sema, wiring core, registry, model providers, and cloud agent execution. Built on @sema-agent/core.",
   "type": "module",
   "license": "BUSL-1.1",
@@ -54,7 +54,7 @@
     "build:binary:run-local:darwin-arm64": "bun build --compile --target=bun-darwin-arm64 src/run-local.ts --outfile dist/run-local-darwin-arm64"
   },
   "dependencies": {
-    "@sema-agent/core": "7.20.1",
+    "@sema-agent/core": "7.21.1",
     "@sema-agent/settings-schema": "2.1.0",
     "e2b": "^2.28.0",
     "libsodium-wrappers": "^0.8.4",