@nowcrew/daemon 0.6.89 → 0.6.91-beta.1

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:
@@ -348,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

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-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;
+    }
+}

package/dist/agent-environments.js

@@ -0,0 +1,275 @@
+/** Server 决策生效计划；本模块只做受控文件物化与当前执行目录选择。 */
+import { chmod, lstat, mkdir, open, readFile, readdir, realpath, rename, unlink } from "node:fs/promises";
+import { createHash, randomUUID } from "node:crypto";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { z } from "zod";
+import { acquireProfileSaveLock } from "./computer-profile-lock.js";
+import { AgentEnvironmentPlanSchema } from "./agent-environment-contract.js";
+const STATE_DIRECTORY = ".nowwork-environments";
+const FileHashes = z.record(z.string().regex(/^[a-f0-9]{64}$/u));
+const StateSchema = z.object({
+    revision: z.number().int().nonnegative(), digest: z.string(), files: FileHashes,
+    pending: z.object({ revision: z.number().int().nonnegative(), digest: z.string(), files: FileHashes }).optional(),
+}).strict();
+const digest = (content) => createHash("sha256").update(content).digest("hex");
+const codeOf = (error) => error.code;
+async function safeDirectory(root, path) {
+    let current = root;
+    for (const segment of path.split("/").filter(Boolean)) {
+        if (segment === "." || segment === ".." || segment.includes("\\"))
+            throw new Error("environment_path_invalid");
+        current = join(current, segment);
+        await mkdir(current, { mode: 0o700 }).catch(error => { if (codeOf(error) !== "EEXIST")
+            throw error; });
+        const info = await lstat(current);
+        if (info.isSymbolicLink())
+            throw new Error("environment_path_symlink");
+        if (!info.isDirectory())
+            throw new Error("environment_path_invalid");
+    }
+    return current;
+}
+async function regularFileContent(path) {
+    const info = await lstat(path).catch(error => { if (codeOf(error) === "ENOENT")
+        return null; throw error; });
+    if (!info)
+        return null;
+    if (!info.isFile() || info.isSymbolicLink() || info.nlink > 1)
+        throw new Error("environment_file_unsafe");
+    if (info.size > 8 * 1024 * 1024)
+        throw new Error("environment_file_too_large");
+    return readFile(path, "utf8");
+}
+async function atomicWrite(path, content, beforeCommit) {
+    const temporary = join(dirname(path), `.env-write-${randomUUID()}`);
+    try {
+        const handle = await open(temporary, "wx", 0o600);
+        try {
+            await handle.writeFile(content, "utf8");
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        // stage 的慢 IO 完成后重验归属；最终校验 + rename 不是针对外部编辑器的系统级 CAS。
+        await beforeCommit?.();
+        await rename(temporary, path);
+        await chmod(path, 0o600);
+    }
+    finally {
+        await unlink(temporary).catch(error => { if (codeOf(error) !== "ENOENT")
+            throw error; });
+    }
+}
+async function requireUnchangedFile(path, expectedHash, relativePath) {
+    const current = await regularFileContent(path);
+    if ((current === null ? null : digest(current)) !== expectedHash)
+        throw new Error(`environment_file_conflict:${relativePath}`);
+}
+const relativeFileValid = (path) => /^(?:(?:training|repos\/[A-Za-z0-9][A-Za-z0-9._-]{0,127})\/)?\.env(?:\.[a-z][a-z0-9_-]{0,47})?$/u.test(path);
+export async function withEnvironmentFilesLock(agentRoot, operation) {
+    await mkdir(agentRoot, { recursive: true, mode: 0o700 });
+    const rootInfo = await lstat(agentRoot);
+    if (!rootInfo.isDirectory() || rootInfo.isSymbolicLink())
+        throw new Error("environment_path_symlink");
+    const stateRoot = await safeDirectory(await realpath(agentRoot), STATE_DIRECTORY);
+    const release = await acquireProfileSaveLock(stateRoot);
+    try {
+        return await operation();
+    }
+    finally {
+        await release();
+    }
+}
+const TRAINING_FILE_MARKER = ".nowwork-environment-files.json";
+const trainingFileName = (name) => /^\.env(?:\.[a-z][a-z0-9_-]{0,47})?$/u.test(name);
+const TrainingFileOwnershipSchema = z.object({ files: FileHashes, pending: FileHashes.optional() }).strict();
+const trainingFileHashes = (files) => Object.fromEntries(Object.entries(files).map(([name, content]) => [name, digest(content)]));
+async function trainingFileOwnership(directory) {
+    const text = await regularFileContent(join(directory, TRAINING_FILE_MARKER));
+    if (text === null)
+        return null;
+    try {
+        const ownership = TrainingFileOwnershipSchema.parse(JSON.parse(text));
+        if (Object.keys({ ...ownership.files, ...ownership.pending }).some(name => !trainingFileName(name)))
+            throw new Error();
+        return ownership;
+    }
+    catch {
+        throw new Error("environment_training_state_invalid");
+    }
+}
+/** 训练包安装前，仅接受由环境管理器创建、没有其他用户文件的占位目录。 */
+export async function isEnvironmentOnlyTrainingDirectory(directory) {
+    const ownership = await trainingFileOwnership(directory);
+    const stateText = ownership === null ? await regularFileContent(join(dirname(directory), STATE_DIRECTORY, "state.json")) : null;
+    const state = stateText === null ? null : StateSchema.parse(JSON.parse(stateText));
+    if (ownership === null && state === null)
+        return false;
+    const names = await readdir(directory);
+    for (const name of names) {
+        if (name === TRAINING_FILE_MARKER && ownership !== null)
+            continue;
+        if (!trainingFileName(name))
+            return false;
+        const content = await regularFileContent(join(directory, name));
+        const hash = content === null ? null : digest(content);
+        const owned = ownership === null
+            ? hash !== null && (hash === state?.files[`training/${name}`] || hash === state?.pending?.files[`training/${name}`])
+            : hash !== null && (hash === ownership.files[name] || hash === ownership.pending?.[name]);
+        if (!owned)
+            return false;
+    }
+    return true;
+}
+/** 保存当前全局状态已确认的文件，并给即将移入 rollback 的目录留下独立归属证明。 */
+export async function captureTrainingEnvironmentFiles(agentRoot) {
+    const stateText = await regularFileContent(join(agentRoot, STATE_DIRECTORY, "state.json"));
+    if (!stateText)
+        return {};
+    const state = StateSchema.parse(JSON.parse(stateText));
+    const directory = join(agentRoot, "training");
+    const info = await lstat(directory).catch(error => { if (codeOf(error) === "ENOENT")
+        return null; throw error; });
+    if (info === null)
+        return {};
+    if (!info.isDirectory() || info.isSymbolicLink())
+        throw new Error("environment_path_symlink");
+    await trainingFileOwnership(directory); // 损坏的归属记录不能被静默覆盖。
+    const result = {};
+    for (const name of await readdir(directory)) {
+        if (!trainingFileName(name))
+            continue;
+        const path = `training/${name}`;
+        const content = await regularFileContent(join(directory, name));
+        if (content === null)
+            continue;
+        if (digest(content) !== state.files[path] && digest(content) !== state.pending?.files[path])
+            throw new Error(`environment_file_conflict:${path}`);
+        result[name] = content;
+    }
+    if ((info.mode & 0o200) === 0)
+        await chmod(directory, info.mode | 0o200);
+    await atomicWrite(join(directory, TRAINING_FILE_MARKER), JSON.stringify({ files: trainingFileHashes(result) }));
+    return result;
+}
+/** 发布前收敛完整文件集合；只移除目录自身归属记录确认的旧文件，支持中途失败后重试。 */
+export async function restoreTrainingEnvironmentFiles(directory, files) {
+    const info = await lstat(directory);
+    if (!info.isDirectory() || info.isSymbolicLink())
+        throw new Error("environment_path_symlink");
+    const ownership = await trainingFileOwnership(directory);
+    const names = [...new Set([
+            ...(await readdir(directory)).filter(trainingFileName),
+            ...Object.keys(ownership?.files ?? {}), ...Object.keys(ownership?.pending ?? {}), ...Object.keys(files),
+        ])].sort();
+    const assertOwned = async (name) => {
+        if (!trainingFileName(name))
+            throw new Error("environment_state_path_invalid");
+        const current = await regularFileContent(join(directory, name));
+        if (current !== null && digest(current) !== ownership?.files[name] && digest(current) !== ownership?.pending?.[name]) {
+            throw new Error(`environment_file_conflict:training/${name}`);
+        }
+        return current;
+    };
+    const currentHashes = {};
+    for (const name of names) {
+        const current = await assertOwned(name);
+        if (current !== null)
+            currentHashes[name] = digest(current);
+    }
+    const nextHashes = trainingFileHashes(files);
+    if ((info.mode & 0o200) === 0)
+        await chmod(directory, info.mode | 0o200);
+    await atomicWrite(join(directory, TRAINING_FILE_MARKER), JSON.stringify({ files: currentHashes, pending: nextHashes }));
+    for (const name of names) {
+        const target = join(directory, name);
+        const current = await regularFileContent(target);
+        if (current !== null && digest(current) !== currentHashes[name])
+            throw new Error(`environment_file_conflict:training/${name}`);
+        const content = files[name];
+        if (content === undefined)
+            await unlink(target).catch(error => { if (codeOf(error) !== "ENOENT")
+                throw error; });
+        else {
+            const expectedHash = current === null ? null : digest(current);
+            await atomicWrite(target, content, () => requireUnchangedFile(target, expectedHash, `training/${name}`));
+        }
+    }
+    await atomicWrite(join(directory, TRAINING_FILE_MARKER), JSON.stringify({ files: nextHashes }));
+}
+export async function applyAgentEnvironmentPlan(agentRoot, input) {
+    const parsed = AgentEnvironmentPlanSchema.safeParse(input);
+    // 不让 Zod 的输入值或上游凭据出现在 RPC / console 错误中。
+    if (!parsed.success)
+        throw new Error("environment_plan_invalid");
+    const plan = parsed.data;
+    await mkdir(agentRoot, { recursive: true, mode: 0o700 });
+    const rootInfo = await lstat(agentRoot);
+    if (!rootInfo.isDirectory() || rootInfo.isSymbolicLink())
+        throw new Error("environment_path_symlink");
+    const root = await realpath(agentRoot);
+    const stateRoot = await safeDirectory(root, STATE_DIRECTORY);
+    const release = await acquireProfileSaveLock(stateRoot);
+    try {
+        const statePath = join(stateRoot, "state.json");
+        const stateText = await regularFileContent(statePath);
+        const previous = stateText === null ? null : StateSchema.parse(JSON.parse(stateText));
+        const hash = digest(JSON.stringify(plan));
+        const latest = previous?.pending ?? previous;
+        if (latest && plan.revision < latest.revision)
+            throw new Error("environment_revision_stale");
+        if (latest && plan.revision === latest.revision && hash !== latest.digest)
+            throw new Error("environment_revision_conflict");
+        const nextContents = Object.fromEntries(plan.scopes.flatMap(scope => scope.files.map(file => [
+            scope.path ? `${scope.path}/${file.name}` : file.name, file.content,
+        ])));
+        const nextHashes = Object.fromEntries(Object.entries(nextContents).map(([path, text]) => [path, digest(text)]));
+        const paths = [...new Set([...Object.keys(previous?.files ?? {}), ...Object.keys(previous?.pending?.files ?? {}), ...Object.keys(nextContents)])].sort();
+        // 所有候选先预检，再开始写入，避免可预见的冲突造成半套配置。
+        const currentHashes = {};
+        for (const path of paths) {
+            if (!relativeFileValid(path))
+                throw new Error("environment_state_path_invalid");
+            await safeDirectory(root, path.includes("/") ? path.slice(0, path.lastIndexOf("/")) : "");
+            const current = await regularFileContent(join(root, path));
+            if (current !== null && digest(current) !== previous?.files[path] && digest(current) !== previous?.pending?.files[path]) {
+                throw new Error(`environment_file_conflict:${path}`);
+            }
+            if (current !== null)
+                currentHashes[path] = digest(current);
+        }
+        const pending = { revision: plan.revision, digest: hash, files: nextHashes };
+        await atomicWrite(statePath, JSON.stringify({ revision: previous?.revision ?? 0, digest: previous?.digest ?? "", files: currentHashes, pending }));
+        for (const path of paths) {
+            // 重检目录和文件，确保写入前仍处于托管边界。
+            await safeDirectory(root, path.includes("/") ? path.slice(0, path.lastIndexOf("/")) : "");
+            const target = join(root, path);
+            const current = await regularFileContent(target);
+            if (current !== null && digest(current) !== currentHashes[path]) {
+                throw new Error(`environment_file_conflict:${path}`);
+            }
+            const content = nextContents[path];
+            if (content === undefined)
+                await unlink(target).catch(error => { if (codeOf(error) !== "ENOENT")
+                    throw error; });
+            else {
+                const expectedHash = current === null ? null : digest(current);
+                await atomicWrite(target, content, () => requireUnchangedFile(target, expectedHash, path));
+            }
+        }
+        await atomicWrite(statePath, JSON.stringify(pending));
+        return { revision: plan.revision, files: Object.keys(nextContents).sort() };
+    }
+    finally {
+        await release();
+    }
+}
+/** 按工作目录/绑定项目选择唯一分支；绝不把多个兄弟 Repo 的变量混成进程全局值。 */
+export function environmentForExecution(plan, agentRoot, cwd, projectId) {
+    const selected = projectId === undefined ? undefined : plan.scopes.find(scope => scope.id === `repo:${projectId}`);
+    const path = relative(resolve(agentRoot), resolve(cwd)).split(sep).join("/");
+    const nearest = selected ?? [...plan.scopes].sort((a, b) => b.path.length - a.path.length)
+        .find(scope => scope.path !== "" && (path === scope.path || path.startsWith(`${scope.path}/`)));
+    return { ...(nearest ?? plan.scopes.find(scope => scope.path === ""))?.effective };
+}