@sema-agent/server 7.150.0 → 7.152.0

package/dist/leader/wire.js

@@ -3,30 +3,30 @@ import { parseNumOrFail } from "../config.js";
 import { execFileSync } from "node:child_process";
 import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { randomUUID } from "node:crypto";
 import { tmpdir } from "node:os";
-import { Runner, combinePolicies, createDurableQuestionPolicy, QUESTION_AWAITS_RESUME, delimitUntrusted, hasDestroy, } from "@sema-agent/core";
+import { Runner, delimitUntrusted, hasDestroy, } from "@sema-agent/core";
 import { leaderEntryRefusal, leaderRunEntry } from "./run-entry.js";
 import { buildCheckpointCtx } from "../http/checkpoint-ctx.js";
+import { submissionPermissionModeWrite } from "../permission-mode-admission.js";
 import { serviceVersion } from "../service-version.js";
 import { RemoteContainerExecutionEnv } from "../plugins/remote-env-e2b.js";
 import { buildLaneHomeClaim } from "../execution-lane-caps.js";
 const e2bBaseTemplateHomeSeat = buildLaneHomeClaim({ remoteExec: { provider: "e2b" } });
-import { createDurableAskPolicy } from "../approval.js";
 import { gitSubprocessEnv } from "../server-secret-env.js";
-import { presignS3Url } from "../plugins/s3-presign.js";
-import { buildUploadScript, buildUploadLoopScript, uploadLoopCommand, uploadLoopScriptPath, uploadStepSuffix, fetchUploadedDiff, withStaging, UPLOAD_LOOP_PERIOD_SEC } from "./diffup.js";
+import { buildLeaderDiffUrls, buildUploadScript, buildUploadLoopScript, uploadLoopCommand, uploadLoopScriptPath, uploadStepSuffix, fetchUploadedDiff, withStaging, UPLOAD_LOOP_PERIOD_SEC } from "./diffup.js";
 import { pullDiff, safeRev } from "./diffout.js";
-import { runLeaderTask, withLeaderLeg } from "./leader.js";
+import { LEADER_APPROVAL_SCOPE, leaderLegDurability, runLeaderTask, staticLaneWorkerPark, withLeaderLeg } from "./leader.js";
 import { attachRepairLoopDeps } from "./repair-wire.js";
 import { routePlanWithFallback, validateSubtasks } from "./planner.js";
-import { createEngineNoticeSeat } from "../boot/runner-deps.js";
 import { buildInternalRunCtx } from "../internal-run-env.js";
 import { currentSubject } from "../observability/principal-context.js";
 import { partsOf } from "../owner-brands.js";
 import { taskSpecIdentityOf } from "../engine-identity.js";
 import { redactHead } from "../observability/run-terminal.js";
+import { seatText } from "../trace/exit-seat.js";
+import { SIGV4_PRESIGN_MAX_SEC } from "../object-store-buckets.js";
 const REPAIR_LOOP_WIRED = true;
-export const LEADER_APPROVAL_SCOPE = "_leader";
 export function leaderResourceScope(workerId) {
     return `_leader-resource-${workerId}`;
 }
@@ -104,6 +104,12 @@ function parseNumOrFailNonNegative(name, raw) {
         throw new Error(`env ${name}=${n} must not be negative`);
     return n;
 }
+export function leaderDiffUrlTtlRefusal(presignTtlSec) {
+    if (presignTtlSec <= SIGV4_PRESIGN_MAX_SEC)
+        return undefined;
+    const maxTimeoutMs = (SIGV4_PRESIGN_MAX_SEC - 600) * 1000;
+    return `LEADER_TIMEOUT_MS makes the leader's diff-out links live ${presignTtlSec} s (the worker timeout + 600 s), longer than a presigned URL can (at most ${SIGV4_PRESIGN_MAX_SEC} s (7 days)) — set LEADER_TIMEOUT_MS to at most ${maxTimeoutMs}`;
+}
 export function leaderResourceConfig(env = process.env) {
     const leaderTimeoutMs = Math.max(600_000, Math.floor(parseNumOrFailNonNegative("LEADER_TIMEOUT_MS", env.LEADER_TIMEOUT_MS) || 0) || 86_400_000);
     const workerMaxTurns = Math.floor(parseNumOrFailNonNegative("LEADER_WORKER_MAX_TURNS", env.LEADER_WORKER_MAX_TURNS) || 0) || 10_000;
@@ -199,22 +205,28 @@ export function createLeaderRunner(cfg) {
     };
     const ident = cfg.git ?? { name: "leader", email: "leader@local" };
     const { leaderTimeoutMs, workerLimits, presignTtlSec, resourceSuspend: resourceCfg } = leaderResourceConfig();
+    const ttlRefusal = cfg.s3 !== undefined ? leaderDiffUrlTtlRefusal(presignTtlSec) : undefined;
+    if (ttlRefusal !== undefined)
+        throw new Error(ttlRefusal);
     const { repairRounds, repairBudgetUsd, repairLoopOn, measureGatesOn, repairLoopAttempts, oracleFlakyK, replanBudgetUsd, } = leaderLoopConfig({ repairRounds: cfg.repairRounds });
-    const onNoticeSeat = createEngineNoticeSeat(cfg.logger);
-    const governanceSeat = cfg.governance ?? {};
-    const deploymentPostureSeat = () => cfg.deploymentPosture?.() ?? {};
-    const tracerSeat = cfg.tracer ? { tracer: cfg.tracer } : {};
-    const modsSeat = cfg.mods ? { mods: cfg.mods } : {};
-    const handsSeat = cfg.hands ? { hands: cfg.hands } : {};
-    const servedTableSeat = { models: cfg.models, roles: cfg.roles, ...(cfg.tiers ? { tiers: cfg.tiers } : {}) };
-    const usageWindowSeat = cfg.usageWindows && cfg.usageWindowStore ? { usageWindows: cfg.usageWindows, usageWindowStore: cfg.usageWindowStore } : {};
-    const promptSourceSeat = cfg.promptSource ? { promptSource: cfg.promptSource } : {};
-    const onErrorSeat = cfg.onError ? { onError: cfg.onError } : {};
-    const principalSpec = () => {
-        const subject = currentSubject();
-        return taskSpecIdentityOf(subject === undefined ? undefined : partsOf(subject));
+    const mintLegSessionId = (stem) => `leader-${stem}-${Date.now()}-${randomUUID()}`;
+    const bindLegSlot = (key, env) => {
+        const release = cfg.legSlots.bind(key, env);
+        if (release === undefined)
+            cfg.logger?.warn?.("sandbox_path_env_slot_at_capacity", { sessionId: key, leg: "leader" });
+        return release ?? (() => { });
+    };
+    const withLegSlot = (runner, env, key) => {
+        const orig = runner.runTaskStream.bind(runner);
+        runner.runTaskStream = (...args) => {
+            const release = bindLegSlot(key, env);
+            const stream = orig(...args);
+            void stream.result().then(release, release);
+            return stream;
+        };
+        return runner;
     };
-    const mkRepair = (rawEnv, repoDir, oracleFiles, entry) => {
+    const mkRepair = (rawEnv, repoDir, oracleFiles, birth) => {
         if (repairRounds <= 0)
             return undefined;
         return {
@@ -227,7 +239,6 @@ export function createLeaderRunner(cfg) {
                         throw new Error(`oracle still present after remove (${f.path}) — refusing repair (measurement integrity)`);
                 }
                 try {
-                    const runner = new Runner({ brain: cfg.brain, ...servedTableSeat, pricing: cfg.pricing, ...onNoticeSeat, ...governanceSeat, ...deploymentPostureSeat(), ...tracerSeat, ...usageWindowSeat, ...promptSourceSeat, ...onErrorSeat, ...modsSeat, ...handsSeat, executionEnv: rawEnv, rootPath: repoDir });
                     const objective = [
                         `The integrated project at ${repoDir} fails its build/test. Make the MINIMAL change to the working tree so this command exits 0 (cd into the repo and run it yourself to confirm):`,
                         `  ${testCmd}`,
@@ -236,17 +247,20 @@ export function createLeaderRunner(cfg) {
                         ``,
                         delimitUntrusted("FAILING OUTPUT (untrusted)", errorText),
                     ].join("\n");
+                    const repairSessionId = mintLegSessionId(`repair-${round}`);
+                    const runner = withLegSlot(new Runner({ ...cfg.plane(), executionEnv: rawEnv, rootPath: repoDir }), rawEnv, repairSessionId);
                     const res = await runner
                         .runTaskStream(withLeaderLeg({
                         objective,
-                        ...principalSpec(),
-                        sessionId: `leader-repair-${Date.now()}-${round}`,
+                        sessionId: repairSessionId,
                         signal,
                         limits: { maxCostUsd: repairBudgetUsd, maxWalltimeMs: Math.max(300_000, Math.floor(leaderTimeoutMs / 2)) },
-                    }, entry))
+                    }, birth, { slotKey: repairSessionId, durability: leaderLegDurability({ continuation: "in_run" }), executor: { kind: "fresh" } }))
                         .result();
-                    if (res.terminal.kind !== "completed")
-                        throw new Error(`repair round ${round} did not complete (status=${outwardPlane(res.terminal).status})`);
+                    if (res.terminal.kind !== "completed") {
+                        const plane = outwardPlane(res.terminal);
+                        throw new Error(`repair round ${round} did not complete (status=${plane.status}${plane.errorMessage !== undefined ? `: ${plane.errorMessage}` : ""})`);
+                    }
                     return { costUsd: res.stats?.costMicroUsd !== undefined ? res.stats.costMicroUsd / 1e6 : undefined, note: res.result?.slice(0, 200) };
                 }
                 finally {
@@ -274,6 +288,8 @@ export function createLeaderRunner(cfg) {
         const refused = leaderEntryRefusal(entry);
         if (refused !== undefined)
             return { ok: false, reports: [], cancelled: false, error: refused };
+        const subject = currentSubject();
+        const birth = { entry, identity: taskSpecIdentityOf(subject === undefined ? undefined : partsOf(subject)), govern: cfg.govern, baseline: cfg.baseline, auth: cfg.auth };
         const injectOracles = async (env) => {
             const ofs = body.oracleFiles ?? [];
             if (ofs.length === 0)
@@ -295,15 +311,21 @@ export function createLeaderRunner(cfg) {
             if (Array.isArray(body.subtasks) && body.subtasks.length > 0) {
                 return validateSubtasks(body.subtasks);
             }
-            const planRunner = new Runner({ brain: cfg.brain, ...servedTableSeat, pricing: cfg.pricing, ...onNoticeSeat, ...governanceSeat, ...deploymentPostureSeat(), ...tracerSeat, ...usageWindowSeat, ...promptSourceSeat, ...onErrorSeat, ...modsSeat, ...handsSeat });
+            const planRunner = new Runner({ ...cfg.plane() });
+            const routeAuth = birth.auth(undefined);
             const runRoute = async (prompt) => {
                 const res = await planRunner.runTaskStream({
                     objective: prompt,
-                    ...principalSpec(),
-                    sessionId: `leader-route-${Date.now()}`,
+                    ...birth.identity,
+                    getApiKeyAndHeaders: routeAuth,
+                    sessionId: mintLegSessionId("route"),
                     signal,
                     ...(cfg.routerModel ? { model: cfg.routerModel } : { modelRole: "classifier" }),
                 }).result();
+                if (res.terminal.kind !== "completed") {
+                    const plane = outwardPlane(res.terminal);
+                    cfg.logger?.warn?.("plan_route_run_incomplete", { status: plane.status, ...(plane.errorMessage !== undefined ? { err: seatText("operator-log-error", plane.errorMessage) } : {}) });
+                }
                 return res.result ?? "";
             };
             const { subs, collapsed, rawSample } = await routePlanWithFallback(body.objective, runRoute, {
@@ -315,23 +337,18 @@ export function createLeaderRunner(cfg) {
             return subs;
         };
         const provisionWorker = async (sub) => {
-            const sessionId = `leader-${sub.workerId}-${Date.now()}`;
-            const durable = cfg.durable?.();
+            const sessionId = mintLegSessionId(sub.workerId);
+            const factory = cfg.s3 !== undefined && cfg.envFactory !== undefined ? { s3: cfg.s3, envFactory: cfg.envFactory } : undefined;
+            const park = factory !== undefined ? cfg.durable?.() : staticLaneWorkerPark(cfg.durable?.(), cfg.approvalListInForce());
             const resumeBody = { ...entry, objective: sub.spec.objective };
-            const storedResumeCtx = durable !== undefined ? buildCheckpointCtx({ body: resumeBody, unattendedLeg: true, writerVersion: serviceVersion() }, durable.ctxSealer, sessionId) : undefined;
-            let durableSpec = {};
-            if (durable && storedResumeCtx !== undefined) {
-                const d = durable;
-                durableSpec = {
-                    toolPolicy: combinePolicies(createDurableQuestionPolicy(), createDurableAskPolicy({ requireApproval: d.requireApproval, ...(d.deny ? { deny: d.deny } : {}), ...(d.autoBudget ? { autoBudget: d.autoBudget } : {}), ...(d.neverAuto ? { neverAuto: d.neverAuto } : {}) })),
-                    checkpointStore: d.checkpointStore,
-                    durableApproval: { scope: LEADER_APPROVAL_SCOPE, ...(d.ttlMs ? { ttlMs: d.ttlMs } : {}) },
-                    onQuestion: QUESTION_AWAITS_RESUME,
-                };
-                await d.checkpointStore.putCtx(sessionId, storedResumeCtx).catch((e) => {
+            const storedResumeCtx = park !== undefined ? buildCheckpointCtx({ body: resumeBody, unattendedLeg: true, writerVersion: serviceVersion(), permissionModeWrite: submissionPermissionModeWrite(resumeBody) }, park.ctxSealer, sessionId) : undefined;
+            const durability = leaderLegDurability(park === undefined || storedResumeCtx === undefined
+                ? { continuation: "replay", resumeCtx: "unwritten" }
+                : await park.checkpointStore.putCtx(sessionId, storedResumeCtx).then(() => ({ continuation: "replay", resumeCtx: "landed", park }), (e) => {
                     cfg.logger?.warn?.("leader_putctx_failed", { workerId: sub.workerId, err: redactHead(e instanceof Error ? e.message : String(e), 2000) });
-                });
-            }
+                    return { continuation: "replay", resumeCtx: "lost" };
+                }));
+            const durable = durability.kind === "durable" ? durability.park : undefined;
             let resourceSpec = {};
             const repairLoopActive = repairLoopOn && REPAIR_LOOP_WIRED;
             if (repairLoopActive && resourceCfg) {
@@ -348,8 +365,8 @@ export function createLeaderRunner(cfg) {
             else if (resourceCfg && !repairLoopActive) {
                 cfg.logger?.warn?.("leader_resource_suspend_inactive", {
                     workerId: sub.workerId,
-                    reason: !durable
-                        ? "no durable checkpoint store"
+                    reason: durability.kind === "transient"
+                        ? durability.why
                         : !cfg.toolResultStore
                             ? "no durable tool-result store"
                             : "no durable session store",
@@ -360,8 +377,8 @@ export function createLeaderRunner(cfg) {
                 if (!d || storedResumeCtx === undefined)
                     return runner;
                 const orig = runner.runTaskStream.bind(runner);
-                runner.runTaskStream = (spec, resume) => {
-                    const stream = orig(spec, resume);
+                runner.runTaskStream = (...args) => {
+                    const stream = orig(...args);
                     const iv = setInterval(() => {
                         void d.checkpointStore.putCtx(sessionId, storedResumeCtx).catch(() => { });
                     }, 45_000);
@@ -371,16 +388,11 @@ export function createLeaderRunner(cfg) {
                 };
                 return runner;
             };
-            if (cfg.s3 && cfg.envFactory) {
-                const s3 = cfg.s3;
-                const envFactory = cfg.envFactory;
+            if (factory !== undefined) {
+                const { s3, envFactory } = factory;
                 const baseSha = body.baseSha;
                 const seedCmd = body.seedCmd;
-                const key = `${s3.keyPrefix ?? "leader-diff"}/${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}/${sub.workerId}.patch`;
-                const ttl = presignTtlSec;
-                const base = { endpoint: s3.endpoint, bucket: s3.bucket, accessKey: s3.accessKey, secretKey: s3.secretKey, ...(s3.region ? { region: s3.region } : {}), key, expiresSec: ttl };
-                const putUrl = presignS3Url({ ...base, method: "PUT" });
-                const getUrl = presignS3Url({ ...base, method: "GET" });
+                const { putUrl, getUrl } = buildLeaderDiffUrls(s3, sub.workerId, presignTtlSec);
                 const script = buildUploadScript({ repoDir: repo, baseSha, putUrl, workDir: W });
                 const stage = async (env) => {
                     await stageWorkerEnv(env, { seedCmd, repo, branch: sub.branch, uploadScriptPath: `${W}/.leader-upload.sh`, uploadScript: script });
@@ -389,21 +401,22 @@ export function createLeaderRunner(cfg) {
                 return {
                     workerId: sub.workerId, sessionId, branch: sub.branch,
                     baseSha,
-                    runner: keepCtxWarm(new Runner({
-                        brain: cfg.brain, ...servedTableSeat, pricing: cfg.pricing, ...onNoticeSeat, ...governanceSeat, ...deploymentPostureSeat(), ...tracerSeat, ...usageWindowSeat, ...promptSourceSeat, ...onErrorSeat, ...modsSeat, ...handsSeat,
+                    runner: keepCtxWarm(new Runner({ ...cfg.plane(),
                         ...(cfg.toolResultStore ? { toolResultStore: cfg.toolResultStore } : {}),
                         ...(cfg.sessionStore ? { sessionStore: cfg.sessionStore } : {}),
                         executionEnvFactory: async (ctx) => {
                             const env = await envFactory(ctx);
                             assertLeaderOwnedEnvReapable(env, "leader worker sandbox");
+                            const releaseSlot = bindLegSlot(sessionId, env);
                             return withStaging(env, stage, async (e) => {
+                                releaseSlot();
                                 await stopUploadLoop(e, sub.workerId);
                                 await sh(e)(`cd ${repo} && git add -A && git -c user.name='leader-belt' -c user.email='belt@leader' commit -qm 'belt: auto-commit uncommitted worker output' || true; sh ${W}/.leader-upload.sh`);
                             });
                         },
                     })),
                     fetchDiff: () => fetchUploadedDiff(getUrl),
-                    spec: withLeaderLeg({ ...workerLimits, ...sub.spec, ...durableSpec, ...resourceSpec, ...principalSpec(), objective: `${sub.spec.objective}${uploadStepSuffix(W)}` }, resumeBody),
+                    spec: withLeaderLeg({ ...workerLimits, ...sub.spec, ...resourceSpec, objective: `${sub.spec.objective}${uploadStepSuffix(W)}` }, birth, { slotKey: sessionId, durability, executor: { kind: "fresh" } }),
                 };
             }
             if (!cfg.e2bApiKey)
@@ -415,15 +428,15 @@ export function createLeaderRunner(cfg) {
             const baseSha = await sh(env)(`cd ${repo} && git rev-parse HEAD`);
             return {
                 workerId: sub.workerId, sessionId, branch: sub.branch, baseSha,
-                runner: keepCtxWarm(new Runner({ brain: cfg.brain, ...servedTableSeat, pricing: cfg.pricing, ...onNoticeSeat, ...governanceSeat, ...deploymentPostureSeat(), ...tracerSeat, ...usageWindowSeat, ...promptSourceSeat, ...onErrorSeat, ...modsSeat, ...handsSeat, ...(cfg.toolResultStore ? { toolResultStore: cfg.toolResultStore } : {}), ...(cfg.sessionStore ? { sessionStore: cfg.sessionStore } : {}), executionEnv: env })),
+                runner: keepCtxWarm(withLegSlot(new Runner({ ...cfg.plane(), ...(cfg.toolResultStore ? { toolResultStore: cfg.toolResultStore } : {}), ...(cfg.sessionStore ? { sessionStore: cfg.sessionStore } : {}), executionEnv: env }), env, sessionId)),
                 diffEnv: env,
                 destroy: () => env.destroy().then(() => { }),
-                spec: withLeaderLeg({ ...workerLimits, ...sub.spec, ...durableSpec, ...resourceSpec, ...principalSpec() }, resumeBody),
+                spec: withLeaderLeg({ ...workerLimits, ...sub.spec, ...resourceSpec }, birth, { slotKey: sessionId, durability, executor: { kind: "fresh" } }),
             };
         };
         const provisionIntegrationSandbox = async () => {
             if (cfg.envFactory) {
-                const integSessionId = `leader-integ-${Date.now()}`;
+                const integSessionId = mintLegSessionId("integ");
                 const env = await cfg.envFactory(buildInternalRunCtx(integSessionId));
                 const reap = createEnvReaper(env, "leader integration sandbox");
                 try {
@@ -436,7 +449,7 @@ export function createLeaderRunner(cfg) {
                 }
                 const rawEnv = env;
                 const oracleFiles = body.oracleFiles ?? [];
-                const repair = mkRepair(rawEnv, repo, oracleFiles, entry);
+                const repair = mkRepair(rawEnv, repo, oracleFiles, birth);
                 return { env: asIntegrationEnv(env), destroy: reap, ...(repair ? { repair } : {}) };
             }
             if (!cfg.e2bApiKey)
@@ -454,11 +467,12 @@ export function createLeaderRunner(cfg) {
                 await env.destroy().catch(() => { });
                 throw e;
             }
-            return { env: asIntegrationEnv(env), destroy: () => env.destroy().then(() => { }), ...(mkRepair(env, repo, body.oracleFiles ?? [], entry) ? { repair: mkRepair(env, repo, body.oracleFiles ?? [], entry) } : {}) };
+            const repair = mkRepair(env, repo, body.oracleFiles ?? [], birth);
+            return { env: asIntegrationEnv(env), destroy: () => env.destroy().then(() => { }), ...(repair ? { repair } : {}) };
         };
         const push = createCoordinatorPush(body.durableRemote, body.targetRef, ident);
         const deps = {
-            entry,
+            birth,
             signal,
             plan,
             provisionWorker,
@@ -476,7 +490,7 @@ export function createLeaderRunner(cfg) {
         const resolveRepair = async (solo, _sub) => {
             let env;
             if (cfg.envFactory) {
-                const graderSessionId = `leader-grader-${Date.now()}`;
+                const graderSessionId = mintLegSessionId("grader");
                 env = await cfg.envFactory(buildInternalRunCtx(graderSessionId));
             }
             else {

package/dist/leg-facts.d.ts

@@ -1,7 +1,7 @@
 /**
- * 一条腿的**部署事实**(执行车道 · run 技能名册 · 受理见证 · 登记的工作目录 · 继承的项目上下文)—— server 自有的载体,**不搭引擎 spec 的车**。
+ * 一条腿的**部署事实**(执行车道 · run 技能名册 · 受理见证 · 会话绑定 · 继承的项目上下文 · 登记簿默认读层的种子项目)—— server 自有的载体,**不搭引擎 spec 的车**。
  *
- * 规则:`TaskSpec` 是引擎的类型面,上面只放引擎读的成员。本仓装配器(`boot/resolve-spec.ts` 的 `createResolveSpec`)同时还判出五件
+ * 规则:`TaskSpec` 是引擎的类型面,上面只放引擎读的成员。本仓装配器(`boot/resolve-spec.ts` 的 `createResolveSpec`)同时还判出六件
  * 只有 server 自己读的事实 —— 它们以装配器**自己的输出对象**为键登记在这一张表里(单一铸点 {@link mintLegFacts}),由两只漏斗
  * (受理 `http/admission.ts` 的 `prepareSpec` · 续跑 `http/resume-legs.ts` 的 `resolveResumeSpec`)在拿到装配输出的**同一只对象**时
  * 读一次(唯一读口 {@link legFactsOf},读在 `stampSpecRoot` 复制之前),此后作普通值随 `PreparedTaskSubmission.legFacts` /
@@ -19,6 +19,8 @@ import type { ScenarioHands } from "./capabilities/hands-lane.js";
 import type { RunSkillEntry } from "./capabilities/skills.js";
 import type { DelegationRootWitness } from "./delegated-session-owner.js";
 import type { ProjectContext } from "./project-context.js";
+import type { MemorySeed } from "./project-registry.js";
+import type { SessionBindings } from "./session-bindings.js";
 /** 一条腿的部署事实(冻结记录)。 */
 export interface LegFacts {
     /** 执行车道:`none` ⇒ 无手孪生 Runner。读者 = 生产选路器。 */
@@ -28,15 +30,21 @@ export interface LegFacts {
     /** 受理时读根会话行的那一读(会话 id + 住客)。读者 = 腿的会话行记录座(`session-workspace.ts`)。 */
     readonly sessionWitness: DelegationRootWitness;
     /**
-     * 这次提交的根会话登记的工作目录(提交体 `cwd` 经唯一写口 `setSessionCwd` 登记的那一枚;装配器在登记之后读一次)。缺席 = 没登记。
-     * 读者 = 三只组合入口(同步 / 后台 / 续跑腿的梯子与验证门):经 `compositionLegRoot`(`task-cwd.ts`)交给它们驱动的每一条腿当交活方的工作目录。
+     * 这条腿要写在根会话上的绑定(工作目录 · shell 环境 · 继承策略;装配器只算)。读者 = run 认领之后的唯一提交点(`session-bindings.ts` 的 `commitLegBindings`):
+     * 受理的那一刻写这一笔,写了之后才收场 `refused` 的提交由提交出口按回执撤回;以及三只组合入口(同步 / 后台 / 续跑腿的梯子与验证门):工作目录那一格
+     * (这条腿跑在的那一枚)经 `compositionLegRoot`(`task-cwd.ts`)交给它们驱动的每一条腿当交活方的工作目录。
      */
-    readonly registeredCwd?: string;
+    readonly sessionBindings: SessionBindings;
     /**
      * 这条 run 继承到的项目上下文(`project-context.ts`):新提交腿在装配器头部判出的那一份,续跑腿是从续跑重建输入重放的那一份。缺席 = 没继承。
      * 读者 = 提交腿写续跑重建输入的那一笔(`submit-ctx.ts` `persistSubmissionCtx` → `CheckpointCtx.projectContext`):判一次、随 run 冻结。
      */
     readonly projectContext?: ProjectContext;
+    /**
+     * 这条 run 的登记簿默认读层种子(`project-registry.ts`:种子项目 + 判出它的那一位观者;`null` = 提交带了项目、判过,无):新提交腿判出的,续跑腿是从续跑重建输入重放的那一份。
+     * 缺席 = 没什么可判(提交没带项目)或没判过(续跑重放的行早于种子判)。读者 = 提交腿写续跑重建输入的那一笔(`submit-ctx.ts` `persistSubmissionCtx` → `CheckpointCtx.memorySeed`):判一次、随 run 冻结。
+     */
+    readonly memorySeed?: MemorySeed | null;
 }
 /**
  * 铸事实(**单一属主**:只允许 `createResolveSpec` 的出口调用)。同一只对象被第二次铸 ⇒ 当场抛 —— 两个写者是漂移的成因,

package/dist/leg-facts.js

@@ -6,8 +6,9 @@ export function mintLegFacts(resolved, facts) {
         hands: facts.hands,
         skills: Object.freeze(facts.skills.map((e) => Object.freeze({ ...e }))),
         sessionWitness: Object.freeze({ ...facts.sessionWitness }),
-        ...(facts.registeredCwd !== undefined ? { registeredCwd: facts.registeredCwd } : {}),
+        sessionBindings: Object.freeze({ ...facts.sessionBindings, ...(facts.sessionBindings.shellEnv !== undefined ? { shellEnv: Object.freeze({ ...facts.sessionBindings.shellEnv }) } : {}) }),
         ...(facts.projectContext !== undefined ? { projectContext: Object.freeze({ ...facts.projectContext }) } : {}),
+        ...(facts.memorySeed !== undefined ? { memorySeed: facts.memorySeed === null ? null : Object.freeze({ projectId: facts.memorySeed.projectId, viewer: Object.freeze({ ...facts.memorySeed.viewer }) }) } : {}),
     }));
     return resolved;
 }

package/dist/memory-scope.d.ts

@@ -175,27 +175,39 @@ export declare function memoryEngineRootFor(config: Pick<ServiceConfig, "memoryE
  *  记忆搬到 `<localDataRoot>/memory-work`,存量记忆与控制面升级后隐形)。 */
 export declare function fileMemoryEngineRoot(config: Pick<ServiceConfig, "memoryEngineDir">, fallbackRoot?: string): string;
 /**
- * 一条路径的**规范形**(给 {@link judgeMemoryRootOutsideDataRoot} 的 `canonical` 座用的生产实现):
- *  · 既存的绝对路径 ⇒ **原样**交给 `realpath`(`.native`:大小写不敏感的文件系统上返回盘上的拼写;符号链接、macOS 的 `/var` → `/private/var` 在这一步展平)。
+ * 一段路径**在不在盘**的唯一读法(三态,{@link canonicalPathOf} 逐段走用它;host 车道托管判在「读不出就不删」那一臂登记根时也读它):
+ *  · `stat` 得动(跟随符号链接)⇒ `true`(在);
+ *  · `ENOENT` / `ENOTDIR`(这一处不存在、悬空链接的目标不存在、中间一段不是目录)⇒ `false`(不在);
+ *  · 其余错误(`EACCES` 没有搜索权限的段、`ELOOP` 链接成环、I/O 错误……)⇒ **原样抛**(读不出)。读不出不是「不在」:把它读成不在,
+ *    下游的路径包含判就会把一处它根本看不见的目录判成「不在根里」—— 那正是删除面上的 fail-open。
+ */
+export declare function presentOnDisk(p: string): boolean;
+/**
+ * 一条路径的**规范形**(给 {@link judgeMemoryRootOutsideDataRoot} 的 `canonical` 座用的生产实现;host 车道的工作区托管判也读它):
+ *  · 在盘的绝对路径 ⇒ **原样**交给 `realpath`(core `physicalPathOf` = realpath(3):大小写不敏感的文件系统上返回盘上的拼写;符号链接、macOS 的 `/var` → `/private/var` 在这一步展平)。
  *    不先在字串上折 `..`:操作系统在展开符号链接**之后**才折 `..`,`/link/..` 的真身是链接目标的父目录,字串折叠会把它读成 `/`;
- *  · 其余(尚不存在 / 相对)⇒ 绝对化(**不折叠**)后逐段走:既存的前缀每进一段取一次 `realpath`(符号链接在这一步展开),`..` 折在**已展开**的前缀上 ——
- *    与操作系统同序(`/别名/../新目录` 的真身在链接目标的父目录下;先在字串上折会读成别名的父目录,判到另一只挂载上);第一段不存在起,余下是尚不存在的尾巴
+ *  · 其余(尚不在盘 / 相对)⇒ 绝对化(**不折叠**)后逐段走:在盘的前缀每进一段取一次 `realpath`(符号链接在这一步展开),`..` 折在**已展开**的前缀上 ——
+ *    与操作系统同序(`/别名/../新目录` 的真身在链接目标的父目录下;先在字串上折会读成别名的父目录,判到另一只挂载上);第一段不在盘起,余下是尚不在盘的尾巴
  *    (尾巴只做字串规范化,与 `mkdir -p` 建出来的同形)。
  *
- * 为什么按「最深既存祖先」而不是直接 `realpath(p)`:boot 期记忆根常常还没建出来(新数据根),`realpath` 对不存在的路径抛 ENOENT,
- * 而数据根那一侧已经存在、会被展平 —— 两侧拼写空间不一样,同一个目录会被读成「不在其下」。祖先用 `existsSync` 找(它对 ENOENT / ENOTDIR / EACCES / ELOOP
- * 一律答 `false`,不抛),所以走到的那一级一定 stat 得动;`realpath` 仍可能在「探完到取值之间目录被挪走 / 搜索权限被收」的竞态里抛 ——
- * 不在本函数里吞(吞了就是一条无声的降级臂),由 boot 调用点接住并响亮报一行(`memory_engine_dir_check_unavailable`),起服照常。
+ * 为什么按「最深在盘祖先」而不是直接 `realpath(p)`:boot 期记忆根常常还没建出来(新数据根),`realpath` 对不存在的路径抛 ENOENT,
+ * 而数据根那一侧已经存在、会被展平 —— 两侧拼写空间不一样,同一个目录会被读成「不在其下」。
+ *
+ * **读不出就抛**:每一段在不在盘读 {@link presentOnDisk}(三态)—— 不在(`ENOENT` / `ENOTDIR`)才接成尾巴;没有搜索权限的段、成环的链接、`realpath` 在
+ * 「探完到取值之间目录被挪走 / 搜索权限被收」的竞态里失败,一律**原样抛**,不在本函数里吞(吞了就是一条无声的降级臂:把看不见的一段当成「还不存在」,包含判就答
+ * 「不在里面」)。调用方各自接住、按自己的面响亮说「查不了」:起服记忆根判(`memory_engine_dir_check_unavailable`)· 配置根判(`sema_config_root_workspace_check_unavailable`)·
+ * 店的持久性取证(`path_unresolvable`)· host 车道托管判(铸时 ⇒ 这条腿不铸;删前 ⇒ 不删、留给退出兜底)。
  *
- * 取舍:尾巴(不存在的那几段)只比规范化字串,**不折大小写**,尾巴里的 `..` 按字串折:两个只差大小写、且都还不存在的拼写在大小写不敏感的盘上会被读成两处 ——
+ * 取舍:尾巴(不在盘的那几段)只比规范化字串,**不折大小写**,尾巴里的 `..` 按字串折:两个只差大小写、且都还不在盘的拼写在大小写不敏感的盘上会被读成两处 ——
  * 方向是多报一条 warn(这条判据的失败方向),不会漏报。
  */
 export declare function canonicalPathOf(p: string): string;
 /**
  * **路径包含**(含相等)的判官:`child` 是不是 `root` 本身或它的后代 —— `path.relative(canonical(root), canonical(child))` 不是 `..`、不以 `..` 加分隔符起头、也不是绝对路径(跨盘符)。
  * `..` 要按**整段**判:名为 `..data` 的子目录在其下;`startsWith("..")` 会把它读成在其外。`canonical` 座缺省 `path.resolve`(字串规范形),boot 递 {@link canonicalPathOf} 取符号链接展平后的形;
- * 两侧同一只座(先 root、后 child)。读者两处:记忆根「在数据根之外」那一判({@link judgeMemoryRootOutsideDataRoot})与起服时「配置根是不是工作区的祖先」那一判(`sema-config-dir.ts`);
- * 树里别处内联的同形表达式(`boot/deployment-mods.ts` · `plugins/local-data-dir-modes-m39.ts` · `plugins/remote-env-host.ts` · `plugins/worktree-isolation.ts`)不在本次收口范围。
+ * 两侧同一只座(先 root、后 child)。读者三处:记忆根「在数据根之外」那一判({@link judgeMemoryRootOutsideDataRoot})、起服时「配置根是不是工作区的祖先」那一判(`sema-config-dir.ts`)
+ * 与 host 车道工厂托管的两判(`plugins/remote-env-host.ts`,座 = {@link canonicalPathOf}:铸时「腿的目录落在哪只本服务铸的临时根里」· 删前「此刻谁的工作目录在这只根里」);
+ * 树里别处内联的同形表达式(`boot/deployment-mods.ts` · `plugins/local-data-dir-modes-m39.ts` · `plugins/remote-env-host.ts` 的残余镜像写判 · `plugins/worktree-isolation.ts`)不在本次收口范围。
  */
 export declare function pathIsWithin(root: string, child: string, canonical?: (p: string) => string): boolean;
 /** {@link judgeMemoryRootOutsideDataRoot} 的读数:记忆引擎的根落在本机数据根**之外**。三键即 boot 日志行的字段(`hint` 是一句带两条真路径的人话)。 */

package/dist/memory-scope.js

@@ -1,6 +1,6 @@
-import { existsSync, realpathSync } from "node:fs";
+import { statSync } from "node:fs";
 import { dirname, isAbsolute, join, parse, relative, resolve, sep } from "node:path";
-import { FileMemoryEngineBackend, readMemoryLedgerForm, resolveMemoryEngineRoot, deriveControlPlaneDir, formatUserScope, formatProjScope, normalizeMemorySpec } from "@sema-agent/core";
+import { FileMemoryEngineBackend, physicalPathOf, readMemoryLedgerForm, resolveMemoryEngineRoot, deriveControlPlaneDir, formatUserScope, formatProjScope, normalizeMemorySpec } from "@sema-agent/core";
 import { capabilitiesFor, executionLaneOf } from "./execution-lane-caps.js";
 import { errorCodeOf, errorKindOf } from "./observability/err-text.js";
 import { assertMemoryScopeWidth } from "./plugins/memory-key-guards.js";
@@ -111,9 +111,21 @@ export function memoryEngineRootFor(config, localRoot) {
 export function fileMemoryEngineRoot(config, fallbackRoot) {
     return resolveMemoryEngineRoot(config.memoryEngineDir ?? fallbackRoot);
 }
+export function presentOnDisk(p) {
+    try {
+        statSync(p);
+        return true;
+    }
+    catch (e) {
+        const code = e?.code;
+        if (code === "ENOENT" || code === "ENOTDIR")
+            return false;
+        throw e;
+    }
+}
 export function canonicalPathOf(p) {
-    if (isAbsolute(p) && existsSync(p))
-        return realpathSync.native(p);
+    if (isAbsolute(p) && presentOnDisk(p))
+        return physicalPathOf(p);
     const abs = isAbsolute(p) ? p : `${process.cwd()}${sep}${p}`;
     const { root } = parse(abs);
     let existing = root;
@@ -133,8 +145,8 @@ export function canonicalPathOf(p) {
             continue;
         }
         const next = join(existing, seg);
-        if (existsSync(next))
-            existing = realpathSync.native(next);
+        if (presentOnDisk(next))
+            existing = physicalPathOf(next);
         else
             tail.push(seg);
     }

package/dist/memory-sync-client.d.ts

@@ -1,4 +1,4 @@
-import { type memorySyncReportOf, type MemorySyncTransport } from "@sema-agent/core";
+import { type memorySyncReportOf, type MemorySyncLayerReport, type MemorySyncTransport } from "@sema-agent/core";
 import type { ServiceConfig } from "./config-types.js";
 import type { MemoryScopeStores } from "./memory-scope-stores.js";
 import { type OneTimeMigrationWindow } from "./plugins/one-time-migrations.js";
@@ -48,10 +48,37 @@ export declare function memorySyncCursorDirFor(memoryEngineDir: string): string;
  * 加一个词 ⇒ {@link wayOutSentence} 的穷尽 switch 编译红(句子先写好,词才上得了 wire)。
  */
 export type MemorySyncWayOut = "delete_cursor";
-/** ⑦ 一层停驻的读数(读面与运维行同读这一只记录;不带盘路径 —— 路径只进运维行)。 */
+/** 引擎游标拒的 `detail`(轴 + 游标在那一轴上是缺席还是别的值);型取自引擎的同步报告,本仓不另写一份。 */
+type CursorRefusalDetail = NonNullable<Extract<MemorySyncLayerReport, {
+    readonly outcome: "refused";
+}>["detail"]>;
+/** 一层为什么停驻(铸记录的输入):`kind` 与引擎读数经记录上 wire,`why` 句只进运维行的 `note`(不在记录里)。 */
+type ParkCause = {
+    readonly kind: "cursor_refused";
+    readonly detail: CursorRefusalDetail | undefined;
+} | {
+    readonly kind: "cursor_unusable";
+    readonly why: string;
+};
+/**
+ * ⑦ 停驻成因的闭集(词 = {@link ParkCause} 的 `kind`):`cursor_refused` = 同步引擎在游标上拒了这一层(轴与读数见 `axis` / `found`);`cursor_unusable` = 游标文件读不成游标。
+ * 与运维行的 `reason`(本轮的触发原因)是两回事 —— 本词答「为什么停」,不答「哪一轮撞上它」。
+ */
+export type MemorySyncParkCause = ParkCause["kind"];
+/** 引擎游标拒读数的两个闭集(型取自引擎的同步报告,本仓不另写一份):被拒的是哪一轴;游标在那一轴上是缺席(`absent`)还是绑着别的值(`other`)。 */
+export type MemorySyncCursorAxis = CursorRefusalDetail["axis"];
+export type MemorySyncCursorFound = CursorRefusalDetail["found"];
+/**
+ * ⑦ 一层停驻的记录(读面与运维行同读这一只;**整条**就是 `memory-status.memorySync.parked[]` 的条目,所以它不带盘路径 —— 路径只进运维行)。
+ * 在场律:`cause` 恒在;`axis` / `found` ⇔ 成因是 `cursor_refused` 且引擎的读数在闭集内(别的成因、读数不在闭集 ⇒ 两键缺席,不是 `undefined` 值)。
+ * 加一个键 ⇒ 它就上 wire:自铸登记表的键集(`memorySyncParkedKey`)按本型 `satisfies`,漏登是编译红。唯一铸点 = {@link parkedLayerOf}。
+ */
 export interface MemorySyncParkedLayer {
     readonly scope: string;
     readonly wayOut: MemorySyncWayOut;
+    readonly cause: MemorySyncParkCause;
+    readonly axis?: MemorySyncCursorAxis;
+    readonly found?: MemorySyncCursorFound;
 }
 /** M31 一次的读数(测试按它断言)。`window: "closed"` ⇒ 一行都没读。 */
 export interface SyncCursorRelocationM31Report {
@@ -134,4 +161,5 @@ export declare function startMemorySyncRunner(deps: {
     stores: MemoryScopeStores;
     log: MemorySyncLog;
 }): MemorySyncRunner;
+export {};
 //# sourceMappingURL=memory-sync-client.d.ts.map

package/dist/memory-sync-client.js

@@ -55,6 +55,18 @@ export function memorySyncCursorDirFor(memoryEngineDir) {
 }
 const CURSOR_AXES = { scope: true, peer: true, store: true, incarnation: true };
 const CURSOR_FOUND = { absent: true, other: true };
+function parkedLayerOf(scope, cause, wayOut) {
+    switch (cause.kind) {
+        case "cursor_refused":
+            return Object.freeze({ scope, wayOut, cause: cause.kind, ...(cause.detail !== undefined ? { axis: cause.detail.axis, found: cause.detail.found } : {}) });
+        case "cursor_unusable":
+            return Object.freeze({ scope, wayOut, cause: cause.kind });
+        default: {
+            const unhandled = cause;
+            throw new Error(`memory sync: unknown park cause ${JSON.stringify(unhandled)}`);
+        }
+    }
+}
 function wayOutSentence(wayOut, cursorPath) {
     switch (wayOut) {
         case "delete_cursor":
@@ -81,16 +93,12 @@ function parkCauseSentence(cause) {
     }
 }
 class MemorySyncLayerParked extends Error {
-    scope;
     cursorPath;
-    parkCause;
-    wayOut;
+    layer;
     constructor(scope, cursorPath, parkCause, wayOut = "delete_cursor") {
         super(`memory sync: layer ${JSON.stringify(scope)} parked — ${parkCauseSentence(parkCause)}; ${wayOutSentence(wayOut, cursorPath)}`);
-        this.scope = scope;
         this.cursorPath = cursorPath;
-        this.parkCause = parkCause;
-        this.wayOut = wayOut;
+        this.layer = parkedLayerOf(scope, parkCause, wayOut);
     }
 }
 function cursorRefusalOf(err) {
@@ -354,8 +362,7 @@ export function createMemorySyncRunner(opts) {
     let parkedLayers = [];
     const logLayerFailure = (reason, scope, err) => {
         if (err instanceof MemorySyncLayerParked) {
-            const refused = err.parkCause.kind === "cursor_refused" ? err.parkCause.detail : undefined;
-            opts.log.warn("memory_sync_layer_parked", { reason, scope, cursorPath: err.cursorPath, ...(refused !== undefined ? { axis: refused.axis, found: refused.found } : {}), wayOut: err.wayOut, note: err.message });
+            opts.log.warn("memory_sync_layer_parked", { reason, cursorPath: err.cursorPath, ...err.layer, note: err.message });
         }
         else {
             opts.log.warn("memory_sync_layer_failed", { reason, scope, cursorPath: memorySyncCursorPath(memoryEngineDir, scope), err: errorText(err) });
@@ -386,7 +393,7 @@ export function createMemorySyncRunner(opts) {
             catch (err) {
                 calls.push({ scope, thrown: err });
                 if (err instanceof MemorySyncLayerParked)
-                    parkedNow.push({ scope, wayOut: err.wayOut });
+                    parkedNow.push(err.layer);
                 logLayerFailure(reason, scope, err);
             }
         }