@nowcrew/daemon 0.6.88-beta.3 → 0.6.88-beta.30

package/README.md

@@ -3,6 +3,21 @@
 The daemon is NowWork's local execution adapter. It holds a machine credential, keeps one control-plane
 WebSocket open, and launches coding runtimes on that machine. Product policy remains on the server.
 
+## 已完成搬迁后的存储运行
+
+NAS / `NOWWORK_HOME` 搬迁和旧 daemon 布局标准化入口已退役。daemon 不再提供内部
+`storage-migration-worker` / `storage-migration-recover` 命令，不处理 `daemon:migrate`、
+`daemon:storage-doctor`、`daemon:storage-migrate` 或迁移确认消息，也不再声明
+`storage_migration_v1` / `storage_migration_status_v1` / `daemon_layout_migration_v1` 能力。
+
+现有 `installations.json` 即使仍有历史 `storageMigrationId`，也按当前 installation 解析
+Agent、仓库和报告目录；启动、hello 和身份绑定不再读取迁移 receipt、outbox 或备份。
+hello 继续报告布局、环境、Workspace、路径指纹与 ownership，但不再发送迁移 ID。
+每次连接仍须完成 Server 身份绑定后才能执行任务；Workspace 或 Machine 身份不匹配时拒绝执行。
+
+旧布局读取兼容、日常安装/升级、NAS 所有权校验、执行 journal 与 ACK/replay 继续保留。
+退役代码不会删除历史安装字段、迁移记录、receipt、备份或旧数据目录；这些数据的保留与清理另行处理。
+
 ## Run
 
 For a temporary foreground connection, run:
@@ -25,6 +40,50 @@ This compatibility form stays resident in the current terminal and reconnects wi
 `pnpm --filter @nowcrew/daemon daemon`. `crew-daemon run --agent <handle> --channel <id>` is the legacy
 manual one-shot entry.
 
+## Browser-Approved Computer Setup
+
+The Web UI generates a token-free command for a specific Workspace and Machine:
+
+```bash
+npx -y --registry https://registry.npmjs.org --package @nowcrew/daemon@latest nowwork-computer setup /nowcoder-app --machine <machine-uuid> --server-url https://nowwork.nowcoder.com
+```
+
+`nowwork-computer setup` opens a one-time authorization page, prints the user code, polls until an owner or
+admin approves it, then installs the selected daemon through the existing isolated profile and native service
+installer. The command contains no long-lived `sk_machine_*` credential. The issued credential is held
+only in memory until the private profile is written, and becomes permanent after successful finalization.
+Each command run needs a new approval. Browser approval expires after ten minutes; credential exchange starts
+a separate thirty-minute installation window. Failed installations restore the prior credential when still owned
+by that setup. Interrupted setups are reconciled at server startup and every minute.
+Only one unfinished credential exchange can own a Machine at a time; a concurrent setup receives a conflict.
+Use `--no-browser` on hosts without a desktop browser and
+`--json` for machine-readable status output. `--server-url` must be explicit for remote servers; it may also
+come from `CREW_SERVER_URL`.
+
+Alternatively, install both command entries first, then run setup:
+
+```bash
+npm install --global --registry https://registry.npmjs.org @nowcrew/daemon@latest
+nowwork-computer setup --server-url https://nowwork.nowcoder.com /nowcoder-app --machine <machine-uuid>
+```
+
+With `CREW_SERVER_URL=https://nowwork.nowcoder.com` already set, the second command can be shortened to
+`nowwork-computer setup /nowcoder-app --machine <machine-uuid>`. Replace the placeholder with the
+Machine UUID from the Web command. New production setup links use `nowwork.nowcoder.com`;
+the old `nowwork-in.nowcoder.com` hostname remains a production alias for existing profiles and pairing.
+
+The setup flow validates the exact Workspace and Machine UUID and waits for the machine control-plane hello
+to confirm Workspace, Machine, environment, profile, and storage identity. It does not migrate NAS or copy
+existing `.crew` data. Existing `crew-daemon install --server-url ... --api-key ...` and profile lifecycle
+commands remain available as compatibility and recovery entry points.
+
+## Machine Environment
+
+The daemon loads exported variables from its OS account’s bash/zsh configuration on macOS/Linux,
+and native system/user variables on Windows. Agent directory layers override ordinary machine values;
+running tasks keep immutable snapshots. See [machine environment](../docs/machine-environment.md) for
+source rules, refresh behavior, local controls and the Windows native acceptance status.
+
 ## Computer Profiles And Service Lifecycle
 
 Persist a named connection without putting its machine token in shell history or service arguments:
@@ -50,7 +109,8 @@ npx -y --registry https://registry.npmjs.org @nowcrew/daemon@beta install \
   --release-tag beta --registry https://registry.npmjs.org
 ```
 
-The installer selects the fixed `in` layout for `nowwork-in.nowcoder.com` and the fixed `dev` layout for
+The installer selects the fixed production layout for both `nowwork.nowcoder.com` (canonical) and
+`nowwork-in.nowcoder.com` (legacy compatibility), and the fixed `dev` layout for
 `nowwork-dev.nowcoder.com`. It compares the parsed hostname exactly; lookalike suffixes are not accepted.
 An unknown hostname is rejected before any write and reports how to retry with an explicit custom profile:
 
@@ -242,26 +302,26 @@ The stable adapters keep prompts out of provider argv wherever the provider prot
 
 | Runtime | Transport | System/wake input | Native resume |
 | --- | --- | --- | --- |
-| Claude | stream-json CLI | daemon-owned system prompt file | CLI session id |
-| Codex | app-server JSON-RPC over stdio | `developerInstructions` + turn input | `thread/resume` |
-| Kimi | ACP over stdio | `session/prompt` | `session/resume` (`session/load` compatibility fallback) |
-| Hermes | ACP over stdio | `session/prompt` | `session/resume` (`session/load` compatibility fallback) |
-| OpenCode | `run --format json` | stdin | `--session` |
+| Claude | stream-json CLI | daemon-owned system prompt file + user input | CLI session id; thread-bound: matching native SessionStart proof + SDK initialization |
+| Codex | app-server JSON-RPC over stdio | `developerInstructions` + turn input | `thread/resume`; thread-bound: returned id must match |
+| Kimi | ACP over stdio | `session/prompt` | unbound: `session/resume` (`session/load` fallback); thread-bound: cold |
+| Hermes | ACP over stdio | `session/prompt` | unbound: `session/resume` (`session/load` fallback); thread-bound: cold |
+| OpenCode | `run --format json` | stdin | unbound: `--session`; thread-bound: cold |
 | DeepSeek Harness | ACP over stdio | `session/prompt` | none (fresh session per execution) |
 
 Kimi ACP currently requires a Kimi account even when the CLI has a working custom provider. Only for
 the explicit `Authentication required` response, the adapter retries once through Kimi's stream-json
-CLI and carries the same native session id; unrelated ACP failures stay failures. The CLI fallback is
+CLI; only unbound executions can carry a saved native session id. Unrelated ACP failures stay failures. The CLI fallback is
 subject to the Windows UTF-16 argv guard, while protocol-v1 itself remains disabled on Windows until
 durable Job Object ownership is available.
 
 Hermes uses only ACP capabilities advertised by the installed CLI. Model and effort choices come from
 a short-lived discovery session; credentials, provider profiles, plugins, and `HERMES_HOME` remain
-machine-local. A missing resumed ACP session is retried once as a fresh session.
+machine-local. For unbound executions, a missing resumed ACP session is retried once as a fresh session.
 
 OpenCode receives the prompt through stdin and runs with both cwd and `PWD` anchored to the Agent
 workspace. Models and variants come from `opencode models --verbose` (with the plain catalog as a
-compatibility fallback). A missing resumed session is retried once without `--session`; malformed,
+compatibility fallback). For unbound executions, a missing resumed session is retried once without `--session`; malformed,
 empty, incomplete, or explicitly failed JSON streams remain failures. NowWork never writes
 `opencode.json` or replaces `OPENCODE_CONFIG_CONTENT`. The daemon advertises OpenCode as executable
 only when `opencode run --help` exposes `--format`, `--dangerously-skip-permissions`, `--dir`,
@@ -291,8 +351,12 @@ uses fresh sessions and committed text; it does not claim resume, images, MCP, r
 or transcript support. Agent environment variables cannot override `DEEPSEEK_*`, `DSH_*`, or
 `NOWCREW_DEEPSEEK_HARNESS_CONFIG`; those values always come from the daemon service environment.
 
-Codex, Kimi, Hermes, and OpenCode sessions use the same bounded per-task persistence and keyed lease as Claude when they
-run through protocol v1. A first-progress watchdog covers a provider that accepts a turn but remains
+Unbound Codex, Kimi, Hermes, and OpenCode sessions retain the same configured warm/budget policy and keyed
+lease as Claude through protocol v1. Thread-bound Claude/Codex sessions keep their native session across
+warm-cache expiry, token estimates, and turn counts; verified restoration receives only accepted-cursor
+deltas. New sessions and runtimes without verified restoration receive complete current-thread history
+before the business turn. See the [thread context contract](../docs/thread-scoped-native-context.md).
+A first-progress watchdog covers a provider that accepts a turn but remains
 semantically silent; after the first semantic event, the execution's configured total timeout remains
 authoritative so a legitimate long-running tool is not killed for quiet output.
 DeepSeek Harness is execution-v1-only and intentionally skips native session persistence.
@@ -343,9 +407,11 @@ changing the task cwd. Claude receives
 so a machine policy that disables project settings also disables this source even when the projection is
 healthy.
 
-Existing user-level discovery is unchanged. Claude may still load `~/.claude/skills`; Codex may still
-load `$CODEX_HOME/skills`. The DeepSeek Codex variant uses its Agent-private `.codex-deepseek` home.
-Project bindings do not hide or rewrite any of those sources.
+Ordinary Codex always uses the shared user Home: the inherited `CODEX_HOME`, or `~/.codex` when
+unset. There is no Computer-level Home mode or private-Home migration command. Existing user-level
+discovery is unchanged: Claude may still load `~/.claude/skills`, and Codex may load `$CODEX_HOME/skills`
+and `~/.agents/skills`. The DeepSeek Codex variant keeps its Agent-private `.codex-deepseek` Home for
+provider credentials. Project bindings do not hide or rewrite any of those sources.
 
 Binding changes reconcile immediately when the Computer is online. On reconnect the server sends the
 complete binding set for every Agent assigned to that Computer, including empty sets that clear stale
@@ -354,6 +420,15 @@ Runtime launch, which recovers from a missed notification or daemon restart. Ski
 are visible through the symlink immediately; adding, deleting, renaming, or changing frontmatter requires
 a rescan. Web descriptions remain at the last inventory value until that rescan.
 
+## 目录投影测试的平台范围
+
+`test/directory-projection.test.ts` 在所有平台运行，覆盖路径检查、复制发布、只读权限请求及失败恢复。
+其受控文件系统夹具记录目录 `chmod` 请求，但保留宿主目录的写权限，避免把 macOS 的目录重命名规则当作 Windows 行为。
+生产代码的只读保护不受此夹具影响。
+
+`test/directory-projection.windows.test.ts` 仅在 Windows 上运行，使用真实文件系统验证只读目录发布与文件保护。
+非 Windows 的全量测试会明确跳过该文件，不能据此宣称 Windows 原生行为已验证。
+
 ## Reliability
 
 Protocol-v1 lifecycle is `accepted → started → completed`, followed by a server

package/dist/agent-ability/controller.js

@@ -3,7 +3,17 @@ import { resolveAbilityRelease } from "./resolver.js";
 export const normalizeAbilityCommandError = (error, fallback) => {
     const message = error instanceof Error ? error.message : fallback;
     const structured = message.match(/^(ability_[a-z0-9_]+)(?::|$)/u)?.[1];
-    return structured ?? fallback;
+    if (structured)
+        return structured;
+    if (error instanceof Error && "code" in error) {
+        if (error.code === "ENOSPC")
+            return "ability_disk_full";
+        if (error.code === "EACCES" || error.code === "EPERM")
+            return "ability_filesystem_permission_denied";
+        if (error.code === "ENOENT")
+            return "ability_local_file_missing";
+    }
+    return fallback;
 };
 export function createAgentAbilityController(deps) {
     const resolver = deps.resolve ?? resolveAbilityRelease;

package/dist/agent-ability/git-errors.js

@@ -0,0 +1,22 @@
+/** Classify Git failures without returning command arguments or raw stderr. */
+export function abilityGitErrorCode(error) {
+    if (!(error instanceof Error))
+        return "ability_git_failed";
+    if ("code" in error && error.code === "ENOENT")
+        return "ability_git_unavailable";
+    if ("killed" in error && error.killed === true)
+        return "ability_git_timeout";
+    const stderr = "stderr" in error && typeof error.stderr === "string" ? error.stderr : "";
+    if (/no space left on device/i.test(stderr))
+        return "ability_disk_full";
+    if (/host key verification failed|remote host identification has changed/i.test(stderr)) {
+        return "ability_git_host_verification_failed";
+    }
+    if (/permission denied \(publickey|authentication failed|could not read username|repository not found|access denied/i.test(stderr)) {
+        return "ability_git_access_denied";
+    }
+    if (/could not resolve host|could not resolve hostname|connection timed out|connection refused|network is unreachable|could not connect to server/i.test(stderr)) {
+        return "ability_git_network_failed";
+    }
+    return "ability_git_failed";
+}

package/dist/agent-ability/materializer.js

@@ -1,3 +1,4 @@
+import { captureTrainingEnvironmentFiles, isEnvironmentOnlyTrainingDirectory, restoreTrainingEnvironmentFiles, withEnvironmentFilesLock } from "../agent-environments.js";
 import { createHash, randomUUID } from "node:crypto";
 import { chmod, cp, lstat, mkdir, readFile, readdir, readlink, rename, rm, symlink, writeFile } from "node:fs/promises";
 import { basename, dirname, join, relative, resolve, sep } from "node:path";
@@ -315,7 +316,7 @@ const assertManagedTrainingTreeIfPresent = async (root, errorCode) => {
     if (!await isRealDirectory(root))
         throw new Error(errorCode);
     const catalog = await readManagedCatalog(root).catch(() => null);
-    if (catalog?.managedBy !== "nowcrew-agent-training")
+    if (catalog?.managedBy !== "nowcrew-agent-training" && !await isEnvironmentOnlyTrainingDirectory(root))
         throw new Error(errorCode);
     return true;
 };
@@ -404,7 +405,7 @@ const switchTrainingDirectory = async (agentRoot, staging) => {
         throw error;
     }
 };
-const restoreTrainingRollback = async (agentRoot, ability) => {
+const restoreTrainingRollback = async (agentRoot, ability, environmentFiles) => {
     await recoverTrainingSwitch(agentRoot);
     const currentCatalog = await readManagedCatalog(join(agentRoot, "training")).catch(() => null);
     const rollbackRoot = trainingRollbackRoot(agentRoot);
@@ -419,6 +420,8 @@ const restoreTrainingRollback = async (agentRoot, ability) => {
     const discardRoot = trainingDiscardRoot(agentRoot);
     await assertManagedTrainingTreeIfPresent(discardRoot, "ability_training_discard_invalid");
     await removeManagedTree(discardRoot);
+    // 回滚目录先携带当前环境集合，再发布；旧来源文件仅按该目录自己的哈希证明删除。
+    await restoreTrainingEnvironmentFiles(rollbackRoot, environmentFiles);
     await writeTrainingSwitchJournal(agentRoot, { operation: "restore", phase: "prepared" });
     await finishTrainingRestore(agentRoot);
     dslog("ability.workspace.rollback_restored", "Previous Agent training directory restored locally", {
@@ -443,7 +446,7 @@ const activeTrainingRoot = async (agentsRoot, handle, ability) => {
         ? trainingRoot
         : null;
 };
-const materializeWorkspaceTraining = async (agentsRoot, handle, ability) => {
+const materializeWorkspaceTraining = async (agentsRoot, handle, ability, environmentFiles) => {
     let verified;
     try {
         verified = await verifyCache(agentsRoot, ability);
@@ -477,10 +480,10 @@ const materializeWorkspaceTraining = async (agentsRoot, handle, ability) => {
         if (!await isRealDirectory(trainingRoot))
             throw new Error("ability_workspace_training_conflict");
         previousCatalog = await readManagedCatalog(trainingRoot).catch(() => null);
-        if (previousCatalog?.managedBy !== "nowcrew-agent-training") {
+        if (previousCatalog?.managedBy !== "nowcrew-agent-training" && !await isEnvironmentOnlyTrainingDirectory(trainingRoot)) {
             throw new Error("ability_workspace_training_conflict");
         }
-        if (previousCatalog.releaseId === ability.releaseId
+        if (previousCatalog?.releaseId === ability.releaseId
             && previousCatalog.artifactDigest === ability.artifactDigest
             && previousCatalog.projectionDigest === projectionDigest
             && await projectedSkillsComplete(trainingRoot, ability.skills))
@@ -578,6 +581,8 @@ const materializeWorkspaceTraining = async (agentsRoot, handle, ability) => {
                     await copyMissingEntries(previous, target);
             }
         }
+        // staging 同时准备训练资产和环境文件；rename 后即是完整可用的目录。
+        await restoreTrainingEnvironmentFiles(staging, environmentFiles);
         await switchTrainingDirectory(agentRoot, staging);
     }
     catch (error) {
@@ -588,11 +593,17 @@ const materializeWorkspaceTraining = async (agentsRoot, handle, ability) => {
 };
 const ensureWorkspaceTraining = async (agentsRoot, handle, ability) => {
     const agentRoot = join(agentsRoot, handle);
-    await mkdir(agentRoot, { recursive: true });
-    await recoverTrainingSwitch(agentRoot);
-    return await activeTrainingRoot(agentsRoot, handle, ability)
-        ?? await restoreTrainingRollback(agentRoot, ability)
-        ?? await materializeWorkspaceTraining(agentsRoot, handle, ability);
+    return withEnvironmentFilesLock(agentRoot, async () => {
+        await recoverTrainingSwitch(agentRoot);
+        const environmentFiles = await captureTrainingEnvironmentFiles(agentRoot);
+        const trainingRoot = await activeTrainingRoot(agentsRoot, handle, ability)
+            ?? await restoreTrainingRollback(agentRoot, ability, environmentFiles)
+            ?? await materializeWorkspaceTraining(agentsRoot, handle, ability, environmentFiles);
+        const rollback = trainingRollbackRoot(agentRoot);
+        if (await exists(rollback) && await isEnvironmentOnlyTrainingDirectory(rollback))
+            await removeManagedTree(rollback);
+        return trainingRoot;
+    });
 };
 const projectWorkspaceTraining = async (agentsRoot, handle, ability, trainingRoot) => {
     const agentRoot = join(agentsRoot, handle);

package/dist/agent-ability/resolver.js

@@ -7,6 +7,7 @@ import { parse } from "yaml";
 import { z } from "zod";
 import { abilityWorkspaceProjectionPath, DaemonAbilityLockSchema, DaemonAbilityManifestSchema, matchesAbilityBranch, } from "./types.js";
 import { PROJECT_MANIFEST_SOURCE_PATH, ProjectDependencyManifestSchema, } from "../project-dependency-manifest.js";
+import { abilityGitErrorCode } from "./git-errors.js";
 import { normalizeRepositoryIdentity } from "../repository-identity.js";
 const runFile = promisify(execFile);
 const MAX_FILES = 5_000;
@@ -42,6 +43,7 @@ const gitEnv = () => ({
     GIT_CONFIG_NOSYSTEM: "1",
     GIT_CONFIG_GLOBAL: process.platform === "win32" ? "NUL" : "/dev/null",
     GIT_TERMINAL_PROMPT: "0",
+    LC_ALL: "C",
 });
 export const abilitySha256 = (content) => `sha256:${createHash("sha256").update(content).digest("hex")}`;
 export const safeAbilityName = (value) => value.replace(/[^A-Za-z0-9._-]/gu, "_").slice(0, 128);
@@ -73,10 +75,16 @@ const comparePosixPaths = (left, right) => {
     return leftParts.length - rightParts.length;
 };
 const git = async (args, cwd) => {
-    const result = await runFile("git", [...GIT_ARGS, ...args], {
-        ...(cwd ? { cwd } : {}), env: gitEnv(), timeout: 60_000, maxBuffer: 16 * 1024 * 1024,
-    });
-    return result.stdout.trim();
+    try {
+        const result = await runFile("git", [...GIT_ARGS, ...args], {
+            ...(cwd ? { cwd } : {}), env: gitEnv(), timeout: 60_000, maxBuffer: 16 * 1024 * 1024,
+        });
+        return result.stdout.trim();
+    }
+    catch (error) {
+        // 仅回传固定错误分类，不把 Git stderr 中的凭据、仓库地址或本地路径发到界面。
+        throw new Error(abilityGitErrorCode(error));
+    }
 };
 export const parseAbilityRefLine = (line) => {
     const [branch, commit, rawTime, ...extra] = line.split("\t");

package/dist/agent-environment-contract.js

@@ -0,0 +1,55 @@
+import { z } from "zod";
+import { parseEnv } from "node:util";
+export const AGENT_ENVIRONMENTS_CAPABILITY = "agent_environments_v1";
+const identifier = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u;
+const environmentId = /^[a-z][a-z0-9_-]{0,47}$/u;
+export const environmentRelativePath = (value) => value === "" || value === "training"
+    || /^repos\/[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u.test(value);
+const reserved = new Set(["PATH", "HOME", "USERPROFILE", "CODEX_HOME", "CLAUDE_CONFIG_DIR", "XDG_CONFIG_HOME", "XDG_DATA_HOME", "XDG_CACHE_HOME", "GH_CONFIG_DIR", "CLOUDSDK_CONFIG", "NPM_CONFIG_USERCONFIG", "YARN_REGISTRY", "NPM_CONFIG_ALWAYS_AUTH", "QA_REPORT_HUB", "QA_RUNTIME_ROOT", "QA_REPORT_DELIVERY_CONTEXT", "KIMI_MODEL_THINKING_EFFORT"]);
+export const validEnvironmentKey = (key) => /^[A-Za-z_][A-Za-z0-9_]{0,127}$/u.test(key)
+    && !/^(CREW_|NOWWORK_)/iu.test(key) && !reserved.has(key.toUpperCase());
+const ScopeSchema = z.object({
+    id: z.string().min(1).max(160), path: z.string().refine(environmentRelativePath),
+    activeEnvironmentId: z.string().regex(environmentId).nullable(),
+    files: z.array(z.object({
+        name: z.string().regex(/^\.env(?:\.[a-z][a-z0-9_-]{0,47})?$/u),
+        content: z.string().max(256 * 1024).refine(value => !value.includes("\0")),
+    }).strict()).max(21),
+    effective: z.record(z.string().max(4096).refine(value => !value.includes("\0"))),
+}).strict();
+export const AgentEnvironmentPlanSchema = z.object({
+    revision: z.number().int().nonnegative(), scopes: z.array(ScopeSchema).min(1).max(102),
+}).strict().superRefine((plan, context) => {
+    const paths = new Set(), ids = new Set();
+    for (const scope of plan.scopes) {
+        const expectedId = scope.path === "" ? "root" : scope.path === "training" ? "training" : `repo:${scope.path.slice(6)}`;
+        if (scope.id !== expectedId || paths.has(scope.path) || ids.has(scope.id))
+            context.addIssue({ code: "custom", message: "environment_scope_invalid" });
+        paths.add(scope.path);
+        ids.add(scope.id);
+        const names = new Set(scope.files.map(file => file.name));
+        if (names.size !== scope.files.length || (scope.activeEnvironmentId !== null && !names.has(`.env.${scope.activeEnvironmentId}`))) {
+            context.addIssue({ code: "custom", message: "environment_files_invalid" });
+        }
+        if (Object.keys(scope.effective).length > 200 || Object.keys(scope.effective).some(key => !validEnvironmentKey(key))) {
+            context.addIssue({ code: "custom", message: "environment_key_invalid" });
+        }
+        for (const file of scope.files) {
+            const parsed = parseEnv(file.content);
+            if (Object.keys(parsed).some(key => !validEnvironmentKey(key)))
+                context.addIssue({ code: "custom", message: "environment_key_invalid" });
+            if (file.name === ".env" && (Object.keys(parsed).length !== Object.keys(scope.effective).length
+                || Object.entries(scope.effective).some(([key, value]) => parsed[key] !== value))) {
+                context.addIssue({ code: "custom", message: "environment_effective_file_mismatch" });
+            }
+        }
+        if (!names.has(".env") && Object.keys(scope.effective).length > 0)
+            context.addIssue({ code: "custom", message: "environment_effective_file_missing" });
+    }
+    if (!paths.has(""))
+        context.addIssue({ code: "custom", message: "environment_root_missing" });
+});
+export const AgentEnvironmentsApplySchema = z.object({
+    type: z.literal("agent:environments:apply"), reqId: z.string().min(1).max(200),
+    handle: z.string().regex(identifier), plan: AgentEnvironmentPlanSchema,
+}).strict();

package/dist/agent-environment-control.js

@@ -0,0 +1,24 @@
+import { join } from "node:path";
+import { AgentEnvironmentsApplySchema } from "./agent-environment-contract.js";
+import { applyAgentEnvironmentPlan } from "./agent-environments.js";
+export async function handleAgentEnvironmentFrame(decoded, agentsRoot, send) {
+    if (typeof decoded !== "object" || decoded === null || !("type" in decoded)
+        || decoded.type !== "agent:environments:apply")
+        return false;
+    const parsed = AgentEnvironmentsApplySchema.safeParse(decoded);
+    const reqId = "reqId" in decoded && typeof decoded.reqId === "string" ? decoded.reqId.slice(0, 200) : "invalid";
+    if (!parsed.success) {
+        send({ type: "fs:result", reqId, ok: false, error: "environment_plan_invalid" });
+        return true;
+    }
+    try {
+        const data = await applyAgentEnvironmentPlan(join(agentsRoot, parsed.data.handle), parsed.data.plan);
+        send({ type: "fs:result", reqId, ok: true, data });
+    }
+    catch (error) {
+        const message = error instanceof Error && /^environment_[a-z_]+(?::[A-Za-z0-9_./-]+)?$/u.test(error.message)
+            ? error.message : "environment_apply_failed";
+        send({ type: "fs:result", reqId, ok: false, error: message });
+    }
+    return true;
+}

package/dist/agent-environment-execution.js

@@ -0,0 +1,98 @@
+import { providerOwnedEnvironmentKeys } from "./provider-env.js";
+import { createRequire } from "node:module";
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { AgentEnvironmentPlanSchema } from "./agent-environment-contract.js";
+import { applyAgentEnvironmentPlan, environmentForExecution } from "./agent-environments.js";
+import { mergeRuntimeEnvironments, runtimeEnvironmentValue } from "./runtime-environment-merge.js";
+export function environmentDirectoryContains(root, cwd, paths) {
+    const path = paths.relative(root, cwd);
+    return path === "" || (path !== ".." && !path.startsWith(`..${paths.sep}`) && !paths.isAbsolute(path));
+}
+/** 每次执行的不可变变量快照，供 Agent 显式在不同工作目录运行工具时加载。 */
+const RUNNER = `import { readFileSync } from 'node:fs';
+import { dirname, resolve, relative, sep, isAbsolute } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+const snapshot = JSON.parse(readFileSync(resolve(dirname(fileURLToPath(import.meta.url)), 'snapshot.json'), 'utf8'));
+const { default: spawn } = await import(pathToFileURL(snapshot.spawnModule).href);
+const args = process.argv.slice(2);
+if (args[0] !== '--cwd' || !args[1] || args[2] !== '--' || !args[3]) {
+  process.stderr.write('Usage: node run.mjs --cwd <directory> -- <command> [arguments...]\\n'); process.exit(2);
+}
+const cwd = resolve(args[1]);
+const directoryContains = ${environmentDirectoryContains.toString()};
+const matches = snapshot.scopes.filter(s => directoryContains(s.root,cwd,{relative,isAbsolute,sep}));
+const scope = matches.sort((a,b)=>b.root.length-a.root.length)[0] || snapshot.scopes.find(s=>s.id==='root');
+const merge = ${mergeRuntimeEnvironments.toString()};
+let env = {...(snapshot.executionBaseEnvironment ?? process.env)};
+for (const [key,value] of Object.entries(snapshot.ambient)) {
+  for(const existing of Object.keys(env))if(snapshot.platform==='win32'?existing.toUpperCase()===key.toUpperCase():existing===key)delete env[existing];
+  if(value!==null)env[key]=value;
+}
+env = merge([env,scope?.effective||{}],snapshot.platform);
+for (const [key,value] of Object.entries(snapshot.runtimeOverrides)) {for(const existing of Object.keys(env))if(snapshot.platform==='win32'?existing.toUpperCase()===key.toUpperCase():existing===key)delete env[existing];if(value!==null)env[key]=value;}
+const child=spawn(args[3],args.slice(4),{cwd,env,stdio:'inherit',shell:false});
+child.on('error',()=>{process.stderr.write('environment_command_failed\\n');process.exitCode=1;});
+for(const signal of ['SIGINT','SIGTERM'])process.on(signal,()=>child.kill(signal));
+child.on('exit',(code,signal)=>{process.exitCode=code??(signal==='SIGINT'?130:143);});
+`;
+export async function prepareEnvironmentExecutionSnapshot(input) {
+    if (!/^[A-Za-z0-9_-]{1,128}$/u.test(input.executionId))
+        throw new Error("environment_execution_id_invalid");
+    const parsed = AgentEnvironmentPlanSchema.safeParse(input.plan);
+    if (!parsed.success)
+        throw new Error("environment_plan_invalid");
+    // 文件更新失败须终止本次准备，不能使用旧文件却声称新环境已就绪。
+    try {
+        await applyAgentEnvironmentPlan(input.agentRoot, parsed.data);
+    }
+    catch (error) {
+        // 令牌签发后可能已有较新配置落盘。本轮保留签发时快照，不回滚共享文件或丢掉任务。
+        if (!(error instanceof Error) || error.message !== "environment_revision_stale")
+            throw error;
+    }
+    const directory = join(input.runDir, `.environment-${input.executionId}`);
+    await mkdir(directory, { mode: 0o700 });
+    try {
+        const scopes = parsed.data.scopes.map(scope => ({
+            id: scope.id,
+            root: join(input.agentRoot, scope.path),
+            effective: scope.effective,
+        }));
+        for (const project of input.projectRoots ?? []) {
+            scopes.push({ id: `repo:${project.projectId}`, root: project.root,
+                effective: environmentForExecution(parsed.data, input.agentRoot, project.root, project.projectId) });
+        }
+        const keys = [...new Set(parsed.data.scopes.flatMap(scope => Object.keys(scope.effective)))];
+        const platform = input.platform ?? process.platform;
+        const identity = (key) => platform === "win32" ? key.toUpperCase() : key;
+        const providerKeys = providerOwnedEnvironmentKeys(input.runtime ?? "", input.providerConfig ?? {}, keys, platform);
+        const owned = new Map([...providerKeys, ...input.authoritativeKeys ?? []].map(key => [identity(key), key]));
+        const value = (env, key) => runtimeEnvironmentValue(env, key, platform);
+        const snapshot = {
+            revision: parsed.data.revision, scopes, spawnModule: createRequire(import.meta.url).resolve("cross-spawn"),
+            platform,
+            ...(input.executionBaseEnvironment === undefined ? {} : { executionBaseEnvironment: mergeRuntimeEnvironments([input.executionBaseEnvironment], platform) }),
+            ...(input.machineEnvironmentVersion === undefined ? {} : { machineEnvironmentVersion: input.machineEnvironmentVersion }),
+            runtimeOverrides: Object.fromEntries(keys.filter(key => input.runtimeEnvironment !== undefined
+                && (owned.has(identity(key))
+                    || value(input.runtimeEnvironment, key) !== (value(input.selectedEnvironment, key) ?? value(input.ambient, key))))
+                .map(key => { const canonical = owned.get(identity(key)) ?? key; return [canonical, value(input.runtimeEnvironment, canonical) ?? null]; })),
+            ambient: Object.fromEntries(keys.map(key => [key, value(input.ambient, key) ?? null])),
+        };
+        await writeFile(join(directory, "snapshot.json"), JSON.stringify(snapshot), { mode: 0o600, flag: "wx" });
+        await writeFile(join(directory, "run.mjs"), RUNNER, { mode: 0o600, flag: "wx" });
+        return {
+            directory,
+            prompt: `## Per-directory environment configuration\nThis execution uses environment revision ${parsed.data.revision}. `
+                + `Directory layers are independent: Agent root is inherited by training and each repo; sibling repos do not inherit each other. `
+                + `When running a command in a training or repository directory, use the immutable environment harness: `
+                + `\`node ${JSON.stringify(join(directory, "run.mjs"))} --cwd <absolute-directory> -- <command> [arguments...]\`. `
+                + `Changing directory alone does not reload process variables. Do not source mutable .env files or print environment values.`,
+        };
+    }
+    catch (error) {
+        await rm(directory, { recursive: true, force: true });
+        throw error;
+    }
+}