@botlearn-course/daemon 0.0.7 → 0.0.8

package/dist/runtimes/deepseek-tui.js

@@ -111,6 +111,7 @@ export class DeepseekTuiAdapter {
         let handle;
         let countedInFlight = false;
         let releaseTurn;
+        const managedActivationId = this.managedActivationId(opts);
         try {
             // The local server has a process-level kill fallback when turn-scoped interrupt
             // fails. Serialize turns so cancelling one run can never terminate another run.
@@ -126,7 +127,10 @@ export class DeepseekTuiAdapter {
             if (handle.idleTimer)
                 clearTimeout(handle.idleTimer);
             const headers = authHeaders(handle.token);
-            let threadId = opts.sessionId?.trim() || "";
+            // Agent Service model credentials are activation-scoped. The local DeepSeek
+            // server reads them only at process startup, so its native thread cache cannot
+            // safely cross activations; durable Course context rebuilds the new thread.
+            let threadId = managedActivationId ? "" : (opts.sessionId?.trim() || "");
             if (threadId && !isValidThreadId(threadId)) {
                 return {
                     text: "",
@@ -152,7 +156,7 @@ export class DeepseekTuiAdapter {
             const error = runResult.error ?? (text === "" ? emptyCompletionError(handle.stderrTail) : undefined);
             return {
                 text,
-                newSessionId: threadId,
+                newSessionId: managedActivationId ? "" : threadId,
                 ...(runResult.progressDispositions
                     ? { progressDispositions: runResult.progressDispositions }
                     : {}),
@@ -166,7 +170,7 @@ export class DeepseekTuiAdapter {
             const staleSession = Boolean(opts.sessionId) && isMissingThreadHttpError(err);
             return {
                 text: "",
-                newSessionId: staleSession ? "" : (opts.sessionId ?? ""),
+                newSessionId: managedActivationId || staleSession ? "" : (opts.sessionId ?? ""),
                 error: `deepseek-tui: ${message}`,
             };
         }
@@ -174,8 +178,14 @@ export class DeepseekTuiAdapter {
             opts.signal.removeEventListener("abort", onAbort);
             if (handle && countedInFlight) {
                 handle.inFlight = Math.max(0, handle.inFlight - 1);
-                if (!this.explicitServerUrl)
+                if (managedActivationId && !this.explicitServerUrl && handle.inFlight === 0) {
+                    if (PROCESS_POOL.get(POOL_KEY) === handle)
+                        PROCESS_POOL.delete(POOL_KEY);
+                    shutdownHandle(handle, "managed-activation-finished");
+                }
+                else if (!this.explicitServerUrl) {
                     resetIdle(handle, POOL_KEY);
+                }
             }
             releaseTurn?.();
         }
@@ -194,14 +204,23 @@ export class DeepseekTuiAdapter {
                 child: nullChild(),
                 baseUrl: trimTrailingSlash(this.explicitServerUrl),
                 token: this.explicitAuthToken ?? "",
+                managedActivationId: null,
                 closed: false,
                 inFlight: 0,
                 stderrTail: "",
             };
         }
+        const managedActivationId = this.managedActivationId(opts);
         const existing = PROCESS_POOL.get(POOL_KEY);
-        if (existing && !existing.closed)
+        if (existing
+            && !existing.closed
+            && existing.managedActivationId === managedActivationId) {
             return existing;
+        }
+        if (existing) {
+            PROCESS_POOL.delete(POOL_KEY);
+            shutdownHandle(existing, "activation-scope-changed");
+        }
         const port = await findFreePort();
         if (signal.aborted)
             throw abortReason(signal);
@@ -243,6 +262,7 @@ export class DeepseekTuiAdapter {
             child,
             baseUrl,
             token,
+            managedActivationId,
             closed: false,
             inFlight: 0,
             stderrTail: "",
@@ -278,8 +298,8 @@ export class DeepseekTuiAdapter {
         return handle;
     }
     /**
-     * 不设置 DEEPSEEK_RUNTIME_DIR：server 跨 run 池化共享，per-run 目录不成立；
-     * BYOA 直接用用户本机 deepseek 自身的默认状态目录（含已登录凭据）。
+     * 不设置 DEEPSEEK_RUNTIME_DIR：BYOA server 可跨 run 池化，直接使用用户本机
+     * deepseek 默认状态目录（含已登录凭据）；Agent Service server 按 activation 回收。
      */
     spawnEnv(opts, progressMcpConfigPath) {
         const env = {
@@ -291,6 +311,12 @@ export class DeepseekTuiAdapter {
             env.DEEPSEEK_MCP_CONFIG = progressMcpConfigPath;
         return env;
     }
+    managedActivationId(opts) {
+        if (this.explicitServerUrl)
+            return null;
+        const value = opts.env?.BOTLEARN_AGENT_SERVICE_ACTIVATION_ID?.trim();
+        return value || null;
+    }
     async createThread(baseUrl, headers, opts, signal) {
         const body = {
             workspace: opts.cwd,

package/dist/runtimes/engine.js

@@ -90,7 +90,10 @@ export function wrapEngineAdapter(id, engine, opts) {
             const payload = run.payload;
             // DeepSeek persists and replays the native thread history. The durable Course Service
             // conversation is recovery/bootstrap data, not a second history to inject on every turn.
-            const resumesDeepseekThread = id === "deepseek-tui" && Boolean(run.nativeSessionId?.trim());
+            // Agent Service activations intentionally start a fresh local server because their model
+            // credential expires with the turn, so a cached thread id cannot suppress durable context.
+            const managedActivation = Boolean(run.runtimeEnv?.BOTLEARN_AGENT_SERVICE_ACTIVATION_ID?.trim());
+            const resumesDeepseekThread = id === "deepseek-tui" && !managedActivation && Boolean(run.nativeSessionId?.trim());
             const text = resumesDeepseekThread
                 ? (payload.input.text ?? "")
                 : renderConversationInput(payload);

package/dist/runtimes/fake.js

@@ -1,7 +1,35 @@
-import { writeFileSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";
+import { RuntimeExecutionError } from "../types.js";
 /** message 里回显的任务简报截断长度。 */
 const BRIEF_PREVIEW_CHARS = 80;
+const RUNTIME_ERROR_SCENARIO = "[[e2e:runtime-error]]";
+const SLOW_RUNTIME_SCENARIO = "[[e2e:slow]]";
+function configuredStepDelayMs(brief) {
+    if (brief.includes(SLOW_RUNTIME_SCENARIO))
+        return 1_000;
+    const configured = Number(process.env.BOTLEARN_FAKE_RUNTIME_STEP_DELAY_MS ?? 0);
+    if (!Number.isFinite(configured))
+        return 0;
+    return Math.max(0, Math.min(5_000, Math.floor(configured)));
+}
+async function pauseBetweenSteps(signal, runtimeId, brief) {
+    const delayMs = configuredStepDelayMs(brief);
+    throwIfAborted(signal, runtimeId);
+    if (delayMs <= 0)
+        return;
+    await new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            signal.removeEventListener("abort", onAbort);
+            resolve();
+        }, delayMs);
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(new Error(`${runtimeId} runtime aborted`));
+        };
+        signal.addEventListener("abort", onAbort, { once: true });
+    });
+}
 /**
  * 确定性假 runtime：不 spawn 任何进程，直接实现 CourseRuntime。
  * 仅供端到端联调/测试（registry 里 hidden，capabilities 需
@@ -15,18 +43,86 @@ export class FakeRuntime {
     }
     async run(run, sink, signal) {
         const brief = run.payload.input.text ?? "";
-        const finalText = `已根据任务完成草稿。\n\n任务：${brief.slice(0, BRIEF_PREVIEW_CHARS)}`;
+        const draftPath = path.join(run.workspaceDir, "draft.md");
+        const priorDraft = existsSync(draftPath) ? readFileSync(draftPath, "utf8") : "";
+        const isContinuation = priorDraft.length > 0;
+        if (isContinuation && run.contextRevision !== undefined && !run.nativeSessionId) {
+            throw new RuntimeExecutionError("E2E FakeRuntime lost its native session between turns", "runtime_unavailable");
+        }
+        if (!isContinuation && run.contextRevision !== undefined) {
+            await sink.runtimeSession?.(`fake-thread-${run.payload.course_run_id}`);
+        }
+        const draft = isContinuation
+            ? [
+                "# E2E 草稿",
+                "",
+                "第一段：这是由真实 Course Daemon 协议生成的初稿内容。",
+                "",
+                "第二段：本轮读取并延续了上一轮工作区中的 draft.md。",
+            ].join("\n")
+            : [
+                "# E2E 草稿",
+                "",
+                "第一段：这是由真实 Course Daemon 协议生成的初稿内容。",
+            ].join("\n");
+        const finalText = isContinuation
+            ? `已读取同一工作区的上一轮 draft.md，并补全为标题和两段正文。\n\n${draft}`
+            : `已生成包含标题和第一段正文的初稿，请检查后继续完善。\n\n${draft}\n\n任务：${brief.slice(0, BRIEF_PREVIEW_CHARS)}`;
         const blocks = [
-            { kind: "status", text: "fake runtime started", raw: { event: "started" } },
-            { kind: "thinking", text: "正在起草……", raw: { event: "thinking" } },
-            { kind: "text", text: finalText, raw: { event: "text" } },
+            {
+                kind: "status",
+                text: "deterministic runtime started",
+                raw: { event: "started" },
+            },
+            {
+                kind: "thinking",
+                phase: "in_progress",
+                text: "正在检查任务和工作区。",
+                raw: { event: "reasoning" },
+            },
+            {
+                kind: "tool_call",
+                name: "write_file",
+                text: "draft.md",
+                raw: { event: "tool_call" },
+            },
+            {
+                kind: "progress",
+                runtime: this.id,
+                summary: isContinuation ? "正在补全草稿" : "正在生成初稿",
+                status: "in_progress",
+            },
         ];
         for (const block of blocks) {
             throwIfAborted(signal, this.id);
             await sink.block(block);
+            await pauseBetweenSteps(signal, this.id, brief);
+        }
+        if (brief.includes(RUNTIME_ERROR_SCENARIO)) {
+            throw new RuntimeExecutionError("E2E deterministic runtime failure");
         }
         throwIfAborted(signal, this.id);
-        writeFileSync(path.join(run.workspaceDir, "draft.md"), finalText, "utf8");
+        writeFileSync(draftPath, draft, "utf8");
+        await sink.block({
+            kind: "tool_result",
+            name: "write_file",
+            status: "completed",
+            text: "draft.md",
+            raw: { event: "tool_result" },
+        });
+        await pauseBetweenSteps(signal, this.id, brief);
+        await sink.block({
+            kind: "thinking",
+            phase: "completed",
+            raw: { event: "reasoning" },
+        });
+        await sink.block({
+            kind: "progress",
+            runtime: this.id,
+            summary: isContinuation ? "草稿已补全" : "初稿已生成",
+            status: "completed",
+        });
+        await sink.block({ kind: "text_delta", text: finalText, raw: { event: "text" } });
         await sink.message(finalText);
     }
 }

package/dist/sandbox-supervisor.d.ts

@@ -1,4 +1,4 @@
 #!/usr/bin/env node
-export declare function acquireSessionSupervisorLock(runtimeSessionId: string, lockRoot?: string): (() => void) | null;
+export declare function acquireSandboxSupervisorLock(sandboxId: string, lockRoot?: string): (() => void) | null;
 export declare function runSandboxSupervisor(argv: string[]): Promise<number>;
 export declare function isMainModule(entry?: string): boolean;

package/dist/sandbox-supervisor.js

@@ -49,8 +49,8 @@ async function readOneShotBootstrap() {
         throw new Error("sandbox supervisor bootstrap is empty");
     return Buffer.concat(chunks);
 }
-export function acquireSessionSupervisorLock(runtimeSessionId, lockRoot = SUPERVISOR_LOCK_ROOT) {
-    const lockDir = path.join(lockRoot, runtimeSessionId);
+export function acquireSandboxSupervisorLock(sandboxId, lockRoot = SUPERVISOR_LOCK_ROOT) {
+    const lockDir = path.join(lockRoot, sandboxId);
     const pidFile = path.join(lockDir, "pid");
     mkdirSync(lockRoot, { recursive: true, mode: 0o700 });
     try {
@@ -84,23 +84,23 @@ export function acquireSessionSupervisorLock(runtimeSessionId, lockRoot = SUPERV
         }
     };
 }
-function prepareDirectories(controlUid, controlGid, runtimeUid, runtimeSessionId, sessionGeneration) {
+function prepareDirectories(controlUid, controlGid) {
     mkdirSync(CONTROL_HOME, { recursive: true, mode: 0o700 });
     chownSync("/home/botlearn-control/.botlearn-course", controlUid, controlGid);
     chownSync(CONTROL_HOME, controlUid, controlGid);
     chmodSync(CONTROL_HOME, 0o700);
-    mkdirSync(RUNTIME_PROFILE_ROOT, { recursive: true, mode: 0o750 });
+    mkdirSync(RUNTIME_PROFILE_ROOT, { recursive: true, mode: 0o710 });
     chownSync(RUNTIME_PROFILE_ROOT, controlUid, controlGid);
-    chmodSync(RUNTIME_PROFILE_ROOT, 0o750);
-    mkdirSync(WORKSPACE, { recursive: true, mode: 0o770 });
-    chownSync(WORKSPACE, runtimeUid, controlGid);
-    chmodSync(WORKSPACE, 0o770);
-    const sessionWorkspace = path.join(WORKSPACE, runtimeSessionId, `generation-${sessionGeneration}`);
-    mkdirSync(sessionWorkspace, { recursive: true, mode: 0o770 });
-    chownSync(path.join(WORKSPACE, runtimeSessionId), runtimeUid, controlGid);
-    chownSync(sessionWorkspace, runtimeUid, controlGid);
-    chmodSync(path.join(WORKSPACE, runtimeSessionId), 0o770);
-    chmodSync(sessionWorkspace, 0o770);
+    // Runtime can traverse to the active run profile path named in its instructions,
+    // but cannot enumerate profiles belonging to other activations.
+    chmodSync(RUNTIME_PROFILE_ROOT, 0o710);
+    // /workspace 只准备根目录；per-session 子目录
+    // `<root>/<runtime_session_id>/generation-<sandbox_generation>` 由 daemon
+    // （botlearn-control）在 session.open 时创建。根目录只允许 runtime 组穿过，
+    // 不允许列举 session id；daemon 仅在 activation 期间开放目标子目录。
+    mkdirSync(WORKSPACE, { recursive: true, mode: 0o710 });
+    chownSync(WORKSPACE, controlUid, controlGid);
+    chmodSync(WORKSPACE, 0o710);
 }
 export async function runSandboxSupervisor(argv) {
     if (argv.length !== 2 || argv[0] !== "agent-service" || argv[1] !== "session") {
@@ -117,18 +117,18 @@ export async function runSandboxSupervisor(argv) {
     let releaseLock = null;
     try {
         const decoded = JSON.parse(bootstrap.toString("utf8"));
-        const runtimeSessionId = decoded.runtimeSessionId;
-        const sessionGeneration = Number(decoded.sessionGeneration ?? 0);
-        if (typeof runtimeSessionId !== "string" ||
-            !/^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/.test(runtimeSessionId) ||
-            !Number.isInteger(sessionGeneration) ||
-            sessionGeneration < 1) {
-            throw new Error("sandbox supervisor bootstrap session scope is invalid");
+        const sandboxId = decoded.sandboxId;
+        const sandboxGeneration = Number(decoded.sandboxGeneration ?? 0);
+        if (typeof sandboxId !== "string" ||
+            !/^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/.test(sandboxId) ||
+            !Number.isInteger(sandboxGeneration) ||
+            sandboxGeneration < 1) {
+            throw new Error("sandbox supervisor bootstrap sandbox scope is invalid");
         }
-        releaseLock = acquireSessionSupervisorLock(runtimeSessionId);
+        releaseLock = acquireSandboxSupervisorLock(sandboxId);
         if (releaseLock === null)
             return 0;
-        prepareDirectories(controlUid, controlGid, runtimeUid, runtimeSessionId, sessionGeneration);
+        prepareDirectories(controlUid, controlGid);
         child = spawn(NODE_BINARY, [
             DAEMON_ENTRY,
             "agent-service",

package/dist/workspace.d.ts

@@ -18,14 +18,37 @@ export declare function runWorkspaceDir(agentRunId: string): string;
 export declare function transcriptPath(agentRunId: string): string;
 export declare function runtimeProfileDir(agentRunId: string): string;
 export declare function runtimeProfileRunRootDir(agentRunId: string): string;
-export declare function runtimeSessionRootDir(runtimeSessionId: string, sessionGeneration: number): string;
-export declare function runtimeSessionWorkspaceDir(runtimeSessionId: string, sessionGeneration: number): string;
-export declare function runtimeSessionTranscriptPath(runtimeSessionId: string, sessionGeneration: number, agentRunId: string): string;
+export declare function runtimeSessionRootDir(runtimeSessionId: string, sandboxGeneration: number): string;
+/**
+ * per-session workspace（ADR-015 §7）：managed sandbox 下为
+ * `<BOTLEARN_AGENT_SERVICE_WORKSPACE_ROOT>/<runtime_session_id>/generation-<sandbox_generation>`，
+ * 由 daemon 在 session.open 时创建。
+ */
+export declare function runtimeSessionWorkspaceDir(runtimeSessionId: string, sandboxGeneration: number): string;
+export declare function runtimeSessionTranscriptPath(runtimeSessionId: string, sandboxGeneration: number, agentRunId: string): string;
 export declare function ensureRunWorkspace(agentRunId: string): {
     rootDir: string;
     workspaceDir: string;
 };
-export declare function ensureRuntimeSessionWorkspace(runtimeSessionId: string, sessionGeneration: number, agentRunId: string): {
+/**
+ * session.open 时创建 per-session 目录。managed workspace 默认保持 0700，只有当前
+ * activation 会通过 exposeRuntimeSessionWorkspace() 临时开放给 runtime 组。
+ */
+export declare function ensureRuntimeSessionDirectories(runtimeSessionId: string, sandboxGeneration: number): {
+    rootDir: string;
+    workspaceDir: string;
+};
+/**
+ * 暴露当前 activation 的 managed workspace。sandbox 根目录由 supervisor 设为
+ * 0710，因此 runtime 只能穿过根目录，不能列举其他 session id；未激活 session
+ * 的父目录与 workspace 始终为 0700。
+ */
+export declare function exposeRuntimeSessionWorkspace(runtimeSessionId: string, sandboxGeneration: number): void;
+/** Revoke a managed workspace without deleting the session's durable local materialization. */
+export declare function revokeRuntimeSessionWorkspace(runtimeSessionId: string, sandboxGeneration: number): void;
+/** session.close 时删除 workspace 与本地 session 物化状态（transcripts 等）。幂等。 */
+export declare function removeRuntimeSessionWorkspace(runtimeSessionId: string, sandboxGeneration: number): void;
+export declare function ensureRuntimeSessionWorkspace(runtimeSessionId: string, sandboxGeneration: number, agentRunId: string): {
     rootDir: string;
     workspaceDir: string;
     transcriptFile: string;

package/dist/workspace.js

@@ -1,4 +1,4 @@
-import { chmodSync, existsSync, mkdirSync } from "node:fs";
+import { chmodSync, mkdirSync, rmSync } from "node:fs";
 import path from "node:path";
 import { daemonHome } from "./auth-store.js";
 /**
@@ -42,34 +42,51 @@ export function runtimeProfileDir(agentRunId) {
 export function runtimeProfileRunRootDir(agentRunId) {
     return path.dirname(runtimeProfileDir(agentRunId));
 }
-export function runtimeSessionRootDir(runtimeSessionId, sessionGeneration) {
+export function runtimeSessionRootDir(runtimeSessionId, sandboxGeneration) {
     assertSafeId(runtimeSessionId, "runtime_session_id");
-    if (!Number.isInteger(sessionGeneration) || sessionGeneration < 1) {
-        throw new Error("unsafe session_generation: expected a positive integer");
+    if (!Number.isInteger(sandboxGeneration) || sandboxGeneration < 1) {
+        throw new Error("unsafe sandbox_generation: expected a positive integer");
     }
-    return path.join(daemonHome(), "agent-service-sessions", runtimeSessionId, `generation-${sessionGeneration}`);
+    return path.join(daemonHome(), "agent-service-sessions", runtimeSessionId, `generation-${sandboxGeneration}`);
 }
-export function runtimeSessionWorkspaceDir(runtimeSessionId, sessionGeneration) {
+/**
+ * per-session workspace（ADR-015 §7）：managed sandbox 下为
+ * `<BOTLEARN_AGENT_SERVICE_WORKSPACE_ROOT>/<runtime_session_id>/generation-<sandbox_generation>`，
+ * 由 daemon 在 session.open 时创建。
+ */
+export function runtimeSessionWorkspaceDir(runtimeSessionId, sandboxGeneration) {
+    assertSafeId(runtimeSessionId, "runtime_session_id");
+    if (!Number.isInteger(sandboxGeneration) || sandboxGeneration < 1) {
+        throw new Error("unsafe sandbox_generation: expected a positive integer");
+    }
     const managedRoot = process.env.BOTLEARN_AGENT_SERVICE_WORKSPACE_ROOT?.trim();
     if (managedRoot) {
-        return path.join(managedRoot, runtimeSessionId, `generation-${sessionGeneration}`);
+        return path.join(managedRoot, runtimeSessionId, `generation-${sandboxGeneration}`);
     }
-    return path.join(runtimeSessionRootDir(runtimeSessionId, sessionGeneration), "workspace");
+    return path.join(runtimeSessionRootDir(runtimeSessionId, sandboxGeneration), "workspace");
+}
+function managedRuntimeSessionParentDir(runtimeSessionId) {
+    assertSafeId(runtimeSessionId, "runtime_session_id");
+    const managedRoot = process.env.BOTLEARN_AGENT_SERVICE_WORKSPACE_ROOT?.trim();
+    return managedRoot ? path.join(managedRoot, runtimeSessionId) : null;
 }
-export function runtimeSessionTranscriptPath(runtimeSessionId, sessionGeneration, agentRunId) {
+export function runtimeSessionTranscriptPath(runtimeSessionId, sandboxGeneration, agentRunId) {
     assertSafeId(agentRunId, "agent_run_id");
-    return path.join(runtimeSessionRootDir(runtimeSessionId, sessionGeneration), "transcripts", `${agentRunId}.jsonl`);
+    return path.join(runtimeSessionRootDir(runtimeSessionId, sandboxGeneration), "transcripts", `${agentRunId}.jsonl`);
 }
 // recursive mkdir 只对新建目录生效 mode，已存在目录需 best-effort 收紧。
-function mkdirTolerant(dir) {
-    mkdirSync(dir, { recursive: true, mode: 0o700 });
+function mkdirTolerant(dir, mode = 0o700) {
+    mkdirSync(dir, { recursive: true, mode });
     try {
-        chmodSync(dir, 0o700);
+        chmodSync(dir, mode);
     }
     catch {
         // Windows 等不支持 chmod 时忽略。
     }
 }
+function isMissingPathError(error) {
+    return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
 export function ensureRunWorkspace(agentRunId) {
     const rootDir = runRootDir(agentRunId);
     const workspaceDir = runWorkspaceDir(agentRunId);
@@ -77,19 +94,75 @@ export function ensureRunWorkspace(agentRunId) {
     mkdirTolerant(workspaceDir);
     return { rootDir, workspaceDir };
 }
-export function ensureRuntimeSessionWorkspace(runtimeSessionId, sessionGeneration, agentRunId) {
-    const rootDir = runtimeSessionRootDir(runtimeSessionId, sessionGeneration);
-    const workspaceDir = runtimeSessionWorkspaceDir(runtimeSessionId, sessionGeneration);
-    const transcriptFile = runtimeSessionTranscriptPath(runtimeSessionId, sessionGeneration, agentRunId);
+/**
+ * session.open 时创建 per-session 目录。managed workspace 默认保持 0700，只有当前
+ * activation 会通过 exposeRuntimeSessionWorkspace() 临时开放给 runtime 组。
+ */
+export function ensureRuntimeSessionDirectories(runtimeSessionId, sandboxGeneration) {
+    const rootDir = runtimeSessionRootDir(runtimeSessionId, sandboxGeneration);
+    const workspaceDir = runtimeSessionWorkspaceDir(runtimeSessionId, sandboxGeneration);
     mkdirTolerant(rootDir);
-    if (process.env.BOTLEARN_AGENT_SERVICE_WORKSPACE_ROOT?.trim()) {
-        if (!existsSync(workspaceDir)) {
-            throw new Error("managed runtime session workspace was not prepared by the supervisor");
-        }
+    const managedParent = managedRuntimeSessionParentDir(runtimeSessionId);
+    if (managedParent)
+        mkdirTolerant(managedParent, 0o700);
+    mkdirTolerant(workspaceDir, 0o700);
+    return { rootDir, workspaceDir };
+}
+/**
+ * 暴露当前 activation 的 managed workspace。sandbox 根目录由 supervisor 设为
+ * 0710，因此 runtime 只能穿过根目录，不能列举其他 session id；未激活 session
+ * 的父目录与 workspace 始终为 0700。
+ */
+export function exposeRuntimeSessionWorkspace(runtimeSessionId, sandboxGeneration) {
+    const managedParent = managedRuntimeSessionParentDir(runtimeSessionId);
+    if (!managedParent)
+        return;
+    const { workspaceDir } = ensureRuntimeSessionDirectories(runtimeSessionId, sandboxGeneration);
+    // Parent is traverse-only for the runtime group: allowing group write here would let
+    // the runtime replace the generation directory with a symlink before revoke/cleanup.
+    chmodSync(managedParent, 0o710);
+    chmodSync(workspaceDir, 0o770);
+}
+/** Revoke a managed workspace without deleting the session's durable local materialization. */
+export function revokeRuntimeSessionWorkspace(runtimeSessionId, sandboxGeneration) {
+    const managedParent = managedRuntimeSessionParentDir(runtimeSessionId);
+    if (!managedParent)
+        return;
+    const workspaceDir = runtimeSessionWorkspaceDir(runtimeSessionId, sandboxGeneration);
+    // Revoke the leaf before the parent so a runtime loses access as early as possible.
+    try {
+        chmodSync(workspaceDir, 0o700);
+    }
+    catch (error) {
+        // session.close / generation cleanup may already have removed it. Permission and I/O
+        // failures must remain visible: proceeding would leave an inactive workspace exposed.
+        if (!isMissingPathError(error))
+            throw error;
+    }
+    try {
+        chmodSync(managedParent, 0o700);
+    }
+    catch (error) {
+        if (!isMissingPathError(error))
+            throw error;
     }
-    else {
-        mkdirTolerant(workspaceDir);
+}
+/** session.close 时删除 workspace 与本地 session 物化状态（transcripts 等）。幂等。 */
+export function removeRuntimeSessionWorkspace(runtimeSessionId, sandboxGeneration) {
+    // 校验路径段安全后按 session 整体删除（含全部 generation 与 transcripts）。
+    runtimeSessionRootDir(runtimeSessionId, sandboxGeneration);
+    rmSync(path.join(daemonHome(), "agent-service-sessions", runtimeSessionId), {
+        recursive: true,
+        force: true,
+    });
+    const managedRoot = process.env.BOTLEARN_AGENT_SERVICE_WORKSPACE_ROOT?.trim();
+    if (managedRoot) {
+        rmSync(path.join(managedRoot, runtimeSessionId), { recursive: true, force: true });
     }
+}
+export function ensureRuntimeSessionWorkspace(runtimeSessionId, sandboxGeneration, agentRunId) {
+    const { rootDir, workspaceDir } = ensureRuntimeSessionDirectories(runtimeSessionId, sandboxGeneration);
+    const transcriptFile = runtimeSessionTranscriptPath(runtimeSessionId, sandboxGeneration, agentRunId);
     mkdirTolerant(path.dirname(transcriptFile));
     return { rootDir, workspaceDir, transcriptFile };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botlearn-course/daemon",
-  "version": "0.0.7",
+  "version": "0.0.8",
   "description": "Lightweight BotLearn Course daemon: run course tasks on your own machine with your own agent runtime (BYOA).",
   "type": "module",
   "bin": {

package/dist/agent-service-session.d.ts

@@ -1,67 +0,0 @@
-import { type Logger } from "./log.js";
-import { type PersistentSessionExecution, type PreparedPersistentTurn, type RunReportingClient } from "./run-dispatcher.js";
-import type { CourseRuntime, CourseRuntimeProfile, RunEvent, RunFileCandidate, RunFileRecord, RunStartPayload } from "./types.js";
-export interface AgentServiceSessionOptions {
-    wsUrl: string;
-    sessionId: string;
-    sessionToken: string;
-    runtimes: Map<string, CourseRuntime>;
-    daemonVersion: string;
-    runtimeEnv?: Record<string, string>;
-    log?: Logger;
-    random?: () => number;
-    sleep?: (ms: number) => Promise<void>;
-}
-/** Long-running daemon client for one persistent managed sandbox session. */
-export declare class AgentServiceSessionClient implements RunReportingClient, PersistentSessionExecution {
-    private readonly options;
-    private readonly log;
-    private readonly random;
-    private readonly sleep;
-    private readonly state;
-    private readonly dispatcher;
-    private readonly attempts;
-    private readonly runtimeProfiles;
-    private readonly pendingAcks;
-    private readonly pendingFilePrepares;
-    private readonly pendingFileCommits;
-    private readonly fileGrants;
-    private readonly inflightCommands;
-    private socket;
-    private sessionGeneration;
-    private connectionEpoch;
-    private inboundSeq;
-    private heartbeatMs;
-    private staleMs;
-    private stopped;
-    private permanentFailure;
-    constructor(options: AgentServiceSessionOptions);
-    prepareTurn(payload: RunStartPayload): PreparedPersistentTurn;
-    persistNativeSession(sessionId: string): void;
-    run(): Promise<void>;
-    stop(): void;
-    postEvent(agentRunId: string, event: RunEvent): Promise<void>;
-    postFile(agentRunId: string, file: RunFileCandidate): Promise<RunFileRecord>;
-    uploadFileContent(agentRunId: string, fileId: string, absPath: string, mimeType?: string): Promise<RunFileRecord>;
-    getRunRuntimeProfile(agentRunId: string): Promise<CourseRuntimeProfile>;
-    private connectOnce;
-    private handleHello;
-    private assertServerFrame;
-    private handleServerFrame;
-    private applyDesiredState;
-    private reconcileInterruptedCommand;
-    private runtimeActivation;
-    private ackEventOrFile;
-    private acceptFileGrant;
-    private replaySpool;
-    private sendHeartbeat;
-    private sendCommandAck;
-    private sendControlFrame;
-    private sendFrame;
-    private nextOutboundSeq;
-    private spoolBytes;
-    private enforceSpoolLimit;
-    private rejectPending;
-    private rejectPendingFiles;
-    private persist;
-}