@botlearn-course/daemon 0.0.20-beta.2 → 0.0.20-beta.4

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

@@ -33,8 +33,6 @@ export declare class AgentServiceSandboxClient implements RunReportingClient, Pe
     private readonly dispatcher;
     /** agent_run_id → TURN scope（session/attempt/activation），事件与文件帧路由用。 */
     private readonly turnScopes;
-    private readonly turnWorkspaceCheckpoints;
-    private readonly completedWorkspaceCheckpoints;
     /** 每 run 内嵌 profile（turn payload 自带时优先）。 */
     private readonly runProfiles;
     /** activate 时装配的 per-session profile，turn.start 复用。 */
@@ -111,6 +109,7 @@ export declare class AgentServiceSandboxClient implements RunReportingClient, Pe
     private isCurrentLifecycleFence;
     private runIdsForSession;
     private deactivateSession;
+    private terminateSessionWriters;
     private sameTurnScope;
     private matchesTurnScope;
     private assertTurnScope;

package/dist/agent-service-sandbox.js

@@ -14,7 +14,7 @@ import { RunDispatcher, } from "./run-dispatcher.js";
 import { cleanupRuntimeSessionWorkspaceCopyStaging, copyRuntimeSessionWorkspace, ensureRuntimeSessionDirectories, ensureRuntimeSessionWorkspace, exposeRuntimeSessionWorkspace, finalizeRuntimeSessionWorkspaceCopy, removeRuntimeSessionWorkspace, revokeRuntimeSessionWorkspace, runtimeSessionWorkspaceDir, WORKSPACE_COPY_POLICY_V1, WorkspaceCopyError, workspaceCopyV1Supported, } from "./workspace.js";
 import { readWorkspaceFile, WorkspaceFileReadError } from "./workspace-file-read.js";
 import { checkpointWorkspace, WorkspaceSnapshotControlError, } from "./workspace-snapshot-control.js";
-import { issueWorkspaceQuiescenceProof, quiesceRuntimeWriters, } from "./runtime-quiescence.js";
+import { assertWorkspaceWriterFreezeSupported, freezeRuntimeWriters, issueWorkspaceWriterFreezeProof, quiesceRuntimeWriters, thawRuntimeWriters, } from "./runtime-quiescence.js";
 import { WorkspaceSnapshotStagingError } from "./workspace-snapshot-staging.js";
 import { validateWorkspaceEntrySet, WorkspaceEntrySetError, } from "./workspace-entry-set.js";
 import { WORKSPACE_SNAPSHOT_POLICY_V1, workspaceSnapshotPolicyCapability, } from "./workspace-snapshot-policy.js";
@@ -359,8 +359,6 @@ export class AgentServiceSandboxClient {
     dispatcher;
     /** agent_run_id → TURN scope（session/attempt/activation），事件与文件帧路由用。 */
     turnScopes = new Map();
-    turnWorkspaceCheckpoints = new Map();
-    completedWorkspaceCheckpoints = new Set();
     /** 每 run 内嵌 profile（turn payload 自带时优先）。 */
     runProfiles = new Map();
     /** activate 时装配的 per-session profile，turn.start 复用。 */
@@ -514,15 +512,11 @@ export class AgentServiceSandboxClient {
         const pending = session?.pendingActivationCleanup;
         if (!session || !pending)
             return;
-        await quiesceRuntimeWriters(pending.activationId);
-        revokeRuntimeSessionWorkspace(sessionId, this.sandboxGeneration);
         const activation = this.activationContexts.get(sessionId);
         if (activation?.activationId === pending.activationId) {
             this.activationContexts.delete(sessionId);
             this.sessionProfiles.delete(sessionId);
         }
-        if (session.activationId === pending.activationId)
-            session.activationId = null;
         if (!session.completedActivations.includes(pending.activationId)) {
             // Session-close/generation-rotate are the retention bounds. Never evict an
             // activation tombstone while the session is alive: activation IDs are opaque, so
@@ -537,8 +531,6 @@ export class AgentServiceSandboxClient {
         delete session.acceptedCommands[commandId];
         session.pendingActivationCleanup = null;
         this.turnScopes.delete(pending.agentRunId);
-        if (this.activeSessionId === sessionId)
-            this.activeSessionId = null;
         if (this.currentTurnSessionId === sessionId)
             this.currentTurnSessionId = null;
         this.persist();
@@ -621,9 +613,8 @@ export class AgentServiceSandboxClient {
         if (!this.sandboxGeneration || !this.connectionEpoch) {
             throw new Error("Agent Service sandbox is not authenticated");
         }
-        // Terminal truth is never delayed by object storage. Course Service keeps the
-        // checkpoint obligation pending and, after this turn is ACKed and fully quiesced,
-        // re-delivers it as a session-scoped workspace.checkpoint command.
+        // Terminal truth is never delayed by object storage. Durable workspace checkpointing
+        // is a separate lifecycle command issued only for pause/cleanup/rotation.
         if (event.type === "run.block") {
             await this.waitForEventCapacity();
         }
@@ -863,11 +854,13 @@ export class AgentServiceSandboxClient {
         await cleanupRuntimeSessionWorkspaceCopyStaging();
         this.persist();
         assertRuntimeWorkspaceQuota(process.env.BOTLEARN_AGENT_SERVICE_WORKSPACE_ROOT ?? "");
+        assertWorkspaceWriterFreezeSupported();
         await this.sendControlFrame("sandbox.ready", {
             protocol_versions: [AGENT_SERVICE_WS_SCHEMA],
             capabilities: [
                 WORKSPACE_FILE_READ_BINARY_CAPABILITY,
-                "workspace_snapshot_v1",
+                "workspace_writer_freeze_v1",
+                "workspace_snapshot_v2",
                 "workspace_restore_v1",
                 ...(workspaceCopyV1Supported() ? ["workspace_copy_v1"] : []),
             ],
@@ -1006,6 +999,10 @@ export class AgentServiceSandboxClient {
             case "workspace.checkpoint":
                 this.scheduleLifecycle("workspace.checkpoint", () => this.handleWorkspaceCheckpoint(frame));
                 return;
+            case "workspace.thaw":
+                await thawRuntimeWriters();
+                await this.sendCommandAck(frame, "ok");
+                return;
             case "sandbox.shutdown":
                 await this.stopGracefully();
                 return;
@@ -1033,6 +1030,9 @@ export class AgentServiceSandboxClient {
             this.scheduleLifecycle("sandbox.sync.close", (fence) => this.closeSession(sessionId, "sync_close", frame, fence));
         }
         const state = frame.payload.state;
+        if (frame.payload.thaw_runtime_writers === true) {
+            await thawRuntimeWriters();
+        }
         if (state === "shutdown") {
             await this.stopGracefully();
             return;
@@ -1360,38 +1360,38 @@ export class AgentServiceSandboxClient {
         const checkpointId = frame.payload.checkpoint_id;
         const controlToken = frame.payload.control_token;
         const baseRevision = Number(frame.payload.base_revision);
-        const agentRunId = frame.payload.agent_run_id;
-        const workerAttempt = frame.payload.worker_attempt;
-        const activationId = frame.payload.activation_id;
-        const pendingCleanup = session?.pendingActivationCleanup;
-        if (pendingCleanup &&
-            pendingCleanup.agentRunId === agentRunId &&
-            pendingCleanup.workerAttempt === workerAttempt &&
-            pendingCleanup.activationId === activationId) {
-            await this.completePendingActivationCleanup(sessionId);
-        }
+        const sourceKind = frame.payload.source_kind;
         if (!session ||
-            this.activeSessionId === sessionId ||
             this.currentTurnSessionId === sessionId ||
             typeof checkpointId !== "string" ||
             typeof controlToken !== "string" ||
             controlToken.length < 32 ||
             frame.payload.policy_id !== "WorkspaceSnapshotPolicyV1" ||
+            ![
+                "sandbox_pause",
+                "sandbox_cleanup",
+                "generation_rotation",
+                "initial_migration",
+                "live_workspace_copy",
+                "maintenance_repair",
+            ].includes(String(sourceKind)) ||
             !Number.isSafeInteger(baseRevision) ||
             baseRevision < 0 ||
-            !((agentRunId == null && workerAttempt == null && activationId == null) ||
-                (typeof agentRunId === "string" &&
-                    Number.isSafeInteger(workerAttempt) &&
-                    Number(workerAttempt) >= 1 &&
-                    typeof activationId === "string" &&
-                    activationId.length > 0))) {
+            frame.payload.agent_run_id != null ||
+            frame.payload.worker_attempt != null ||
+            frame.payload.activation_id != null) {
             await this.sendCommandAck(frame, "rejected", "invalid_workspace_checkpoint");
             return;
         }
+        const lifecycleCheckpoint = [
+            "sandbox_pause",
+            "sandbox_cleanup",
+            "generation_rotation",
+        ].includes(String(sourceKind));
+        let checkpointCommitted = false;
         try {
-            revokeRuntimeSessionWorkspace(sessionId, this.sandboxGeneration);
-            await quiesceRuntimeWriters(typeof activationId === "string" ? activationId : null);
-            const quiescenceProof = issueWorkspaceQuiescenceProof({
+            await freezeRuntimeWriters();
+            const freezeProof = issueWorkspaceWriterFreezeProof({
                 sandboxId: this.options.sandboxId,
                 sandboxGeneration: this.sandboxGeneration,
                 runtimeSessionId: sessionId,
@@ -1408,16 +1408,10 @@ export class AgentServiceSandboxClient {
                     sandboxGeneration: this.sandboxGeneration,
                     connectionEpoch: this.connectionEpoch,
                     runtimeSessionId: sessionId,
-                    ...(typeof agentRunId === "string"
-                        ? {
-                            agentRunId,
-                            workerAttempt: Number(workerAttempt),
-                            activationId: String(activationId),
-                        }
-                        : {}),
                 },
-                quiescenceProof,
+                freezeProof,
             });
+            checkpointCommitted = true;
             const marker = readWorkspaceMaterializationMarker(this.options.sandboxId, sessionId);
             if (!marker)
                 throw new Error("workspace checkpoint marker missing");
@@ -1431,8 +1425,13 @@ export class AgentServiceSandboxClient {
                 workspace_content_sha256: marker.contentSha256,
             });
             await this.sendCommandAck(frame, "ok");
+            if (!lifecycleCheckpoint)
+                await thawRuntimeWriters();
         }
         catch (error) {
+            if (!lifecycleCheckpoint || !checkpointCommitted) {
+                await thawRuntimeWriters().catch(() => undefined);
+            }
             this.log.error("workspace baseline checkpoint failed", {
                 sandboxId: this.options.sandboxId,
                 runtimeSessionId: sessionId,
@@ -1583,7 +1582,7 @@ export class AgentServiceSandboxClient {
         const previousSessionId = this.activeSessionId;
         const changesActivation = previousSessionId !== null && (previousSessionId !== sessionId || session.activationId !== activationId);
         if (changesActivation) {
-            const stopped = await this.deactivateSession(previousSessionId);
+            const stopped = await this.deactivateSession(previousSessionId, previousSessionId !== sessionId);
             if (fence && !this.isCurrentLifecycleFence(fence))
                 return;
             if (!stopped) {
@@ -1633,21 +1632,6 @@ export class AgentServiceSandboxClient {
             await this.sendCommandAck(frame, "rejected", "activation_mismatch");
             return;
         }
-        const checkpoint = frame.payload.workspace_checkpoint;
-        if (checkpoint !== undefined) {
-            if (!checkpoint || typeof checkpoint !== "object" || Array.isArray(checkpoint) ||
-                typeof checkpoint.checkpoint_id !== "string" ||
-                checkpoint.policy_id !== "WorkspaceSnapshotPolicyV1" ||
-                !Number.isSafeInteger(checkpoint.base_revision) ||
-                Number(checkpoint.base_revision) < 0) {
-                await this.sendCommandAck(frame, "rejected", "invalid_workspace_checkpoint");
-                return;
-            }
-            this.turnWorkspaceCheckpoints.set(runId, {
-                checkpointId: String(checkpoint.checkpoint_id),
-                baseRevision: Number(checkpoint.base_revision),
-            });
-        }
         const payload = frame.payload;
         if (!this.validTurnPayload(payload)) {
             await this.sendCommandAck(frame, "rejected", "invalid_turn_payload");
@@ -1734,8 +1718,6 @@ export class AgentServiceSandboxClient {
             .finally(() => {
             this.inflightCommands.delete(commandId);
             this.runProfiles.delete(runId);
-            this.turnWorkspaceCheckpoints.delete(runId);
-            this.completedWorkspaceCheckpoints.delete(runId);
         });
     }
     async handleTurnCancel(frame) {
@@ -1796,15 +1778,16 @@ export class AgentServiceSandboxClient {
         const session = this.state.sessions[sessionId];
         if (session) {
             const runIds = this.runIdsForSession(sessionId);
-            session.activationId = null;
             this.activationContexts.delete(sessionId);
             this.sessionProfiles.delete(sessionId);
-            revokeRuntimeSessionWorkspace(sessionId, this.sandboxGeneration);
             for (const runId of runIds)
                 this.dispatcher.cancel(runId);
             if (!await this.dispatcher.waitForRuns(runIds, 10_000)) {
                 throw new Error(`runtime session ${sessionId} did not stop before close`);
             }
+            await this.terminateSessionWriters(session);
+            session.activationId = null;
+            revokeRuntimeSessionWorkspace(sessionId, this.sandboxGeneration);
             if (fence && !this.isCurrentLifecycleFence(fence))
                 return;
             if (this.activeSessionId === sessionId)
@@ -1947,21 +1930,40 @@ export class AgentServiceSandboxClient {
             .filter(([, scope]) => scope.sessionId === sessionId)
             .map(([runId]) => runId);
     }
-    async deactivateSession(sessionId) {
+    async deactivateSession(sessionId, terminateWriters = false) {
         const session = this.state.sessions[sessionId];
         if (!session)
             return true;
         const runIds = this.runIdsForSession(sessionId);
-        session.activationId = null;
         this.activationContexts.delete(sessionId);
         this.sessionProfiles.delete(sessionId);
-        revokeRuntimeSessionWorkspace(sessionId, this.sandboxGeneration);
+        if (terminateWriters) {
+            revokeRuntimeSessionWorkspace(sessionId, this.sandboxGeneration);
+        }
         if (this.activeSessionId === sessionId)
             this.activeSessionId = null;
         for (const runId of runIds)
             this.dispatcher.cancel(runId);
         this.persist();
-        return this.dispatcher.waitForRuns(runIds, 10_000);
+        const stopped = await this.dispatcher.waitForRuns(runIds, 10_000);
+        if (stopped && terminateWriters) {
+            await this.terminateSessionWriters(session);
+        }
+        session.activationId = null;
+        this.persist();
+        return stopped;
+    }
+    async terminateSessionWriters(session) {
+        const activationIds = new Set([
+            ...session.completedActivations,
+            ...(session.activationId ? [session.activationId] : []),
+            ...(session.pendingActivationCleanup?.activationId
+                ? [session.pendingActivationCleanup.activationId]
+                : []),
+        ]);
+        for (const activationId of activationIds) {
+            await quiesceRuntimeWriters(activationId);
+        }
     }
     sameTurnScope(left, right) {
         return left.sessionId === right.sessionId &&

package/dist/agent-service-ws-protocol.d.ts

@@ -1,9 +1,9 @@
-export declare const AGENT_SERVICE_WS_SCHEMA: "botlearn-agent-sandbox-ws/0.3";
-export declare const AGENT_SERVICE_WS_SUBPROTOCOL: "botlearn-agent-sandbox.v3";
+export declare const AGENT_SERVICE_WS_SCHEMA: "botlearn-agent-sandbox-ws/0.4";
+export declare const AGENT_SERVICE_WS_SUBPROTOCOL: "botlearn-agent-sandbox.v4";
 export declare const WORKSPACE_FILE_READ_BINARY_CAPABILITY: "workspace_file_read_binary_v1";
 export declare const WORKSPACE_FILE_CHUNK_BYTES: number;
 export declare const WORKSPACE_FILE_CHUNK_HEADER_BYTES = 29;
-export type SandboxFrameType = "sandbox.hello" | "sandbox.sync" | "session.open" | "session.activate" | "turn.start" | "turn.cancel" | "session.close" | "sandbox.drain" | "sandbox.shutdown" | "event.ack" | "auth.rotate" | "workspace.file.read" | "workspace.checkpoint" | "ping" | "sandbox.ready" | "sandbox.heartbeat" | "command.ack" | "session.opened" | "session.open_failed" | "session.closed" | "turn.event" | "turn.file.report" | "workspace.file.result" | "sandbox.drained" | "sandbox.log" | "pong" | "protocol.error";
+export type SandboxFrameType = "sandbox.hello" | "sandbox.sync" | "session.open" | "session.activate" | "turn.start" | "turn.cancel" | "session.close" | "sandbox.drain" | "sandbox.shutdown" | "event.ack" | "auth.rotate" | "workspace.file.read" | "workspace.checkpoint" | "workspace.thaw" | "ping" | "sandbox.ready" | "sandbox.heartbeat" | "command.ack" | "session.opened" | "session.open_failed" | "session.closed" | "turn.event" | "turn.file.report" | "workspace.file.result" | "sandbox.drained" | "sandbox.log" | "pong" | "protocol.error";
 export declare class UnsupportedSandboxProtocolError extends Error {
     readonly schemaVersion: unknown;
     constructor(schemaVersion: unknown);

package/dist/agent-service-ws-protocol.js

@@ -1,6 +1,6 @@
 import { randomUUID } from "node:crypto";
-export const AGENT_SERVICE_WS_SCHEMA = "botlearn-agent-sandbox-ws/0.3";
-export const AGENT_SERVICE_WS_SUBPROTOCOL = "botlearn-agent-sandbox.v3";
+export const AGENT_SERVICE_WS_SCHEMA = "botlearn-agent-sandbox-ws/0.4";
+export const AGENT_SERVICE_WS_SUBPROTOCOL = "botlearn-agent-sandbox.v4";
 export const WORKSPACE_FILE_READ_BINARY_CAPABILITY = "workspace_file_read_binary_v1";
 export const WORKSPACE_FILE_CHUNK_BYTES = 64 * 1024;
 export const WORKSPACE_FILE_CHUNK_HEADER_BYTES = 29;
@@ -19,6 +19,7 @@ const FRAME_TYPES = new Set([
     "auth.rotate",
     "workspace.file.read",
     "workspace.checkpoint",
+    "workspace.thaw",
     "ping",
     "sandbox.ready",
     "sandbox.heartbeat",

package/dist/file-candidates.js

@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto";
-import { createReadStream } from "node:fs";
+import { constants } from "node:fs";
 import { open, readdir } from "node:fs/promises";
 import path from "node:path";
 import { performance } from "node:perf_hooks";
@@ -20,30 +20,50 @@ function isSafeRelativePath(rel) {
     const segments = rel.split("/");
     return segments.every((seg) => seg !== "" && seg !== "..");
 }
-async function sha256File(absPath) {
+async function sha256File(handle) {
     const hash = createHash("sha256");
-    const stream = createReadStream(absPath);
+    const stream = handle.createReadStream({ autoClose: false, start: 0 });
     for await (const chunk of stream)
         hash.update(chunk);
     return hash.digest("hex");
 }
-async function readPreview(absPath, maxPreviewChars) {
-    const handle = await open(absPath, "r");
+async function readPreview(handle, maxPreviewChars) {
+    const sniff = Buffer.alloc(TEXT_SNIFF_BYTES);
+    const { bytesRead } = await handle.read(sniff, 0, TEXT_SNIFF_BYTES, 0);
+    if (sniff.subarray(0, bytesRead).includes(0))
+        return null;
+    // 预览最多 maxPreviewChars 字符；UTF-8 下 4 字节/字符封顶，读够即可。
+    const want = maxPreviewChars * 4;
+    let buf = sniff.subarray(0, bytesRead);
+    if (bytesRead === TEXT_SNIFF_BYTES && want > TEXT_SNIFF_BYTES) {
+        const more = Buffer.alloc(want - TEXT_SNIFF_BYTES);
+        const extra = await handle.read(more, 0, more.length, TEXT_SNIFF_BYTES);
+        buf = Buffer.concat([buf, more.subarray(0, extra.bytesRead)]);
+    }
+    const text = buf.toString("utf8").replace(/�+$/, "");
+    return redactSecretString(text.slice(0, maxPreviewChars));
+}
+function sameFileVersion(left, right) {
+    return left.dev === right.dev && left.ino === right.ino && left.size === right.size &&
+        left.mtimeNs === right.mtimeNs && left.ctimeNs === right.ctimeNs;
+}
+async function scanStableFile(absPath, maxPreviewChars, maxFileBytes) {
+    const handle = await open(absPath, constants.O_RDONLY | constants.O_NOFOLLOW);
     try {
-        const sniff = Buffer.alloc(TEXT_SNIFF_BYTES);
-        const { bytesRead } = await handle.read(sniff, 0, TEXT_SNIFF_BYTES, 0);
-        if (sniff.subarray(0, bytesRead).includes(0))
-            return null;
-        // 预览最多 maxPreviewChars 字符；UTF-8 下 4 字节/字符封顶，读够即可。
-        const want = maxPreviewChars * 4;
-        let buf = sniff.subarray(0, bytesRead);
-        if (bytesRead === TEXT_SNIFF_BYTES && want > TEXT_SNIFF_BYTES) {
-            const more = Buffer.alloc(want - TEXT_SNIFF_BYTES);
-            const extra = await handle.read(more, 0, more.length, TEXT_SNIFF_BYTES);
-            buf = Buffer.concat([buf, more.subarray(0, extra.bytesRead)]);
+        const before = await handle.stat({ bigint: true });
+        if (!before.isFile() || before.size > BigInt(Number.MAX_SAFE_INTEGER)) {
+            throw new Error("workspace_candidate_invalid_file");
         }
-        const text = buf.toString("utf8").replace(/�+$/, "");
-        return redactSecretString(text.slice(0, maxPreviewChars));
+        const sizeBytes = Number(before.size);
+        if (sizeBytes > maxFileBytes)
+            return { sizeBytes, tooLarge: true };
+        const sha256 = await sha256File(handle);
+        const previewText = await readPreview(handle, maxPreviewChars);
+        const after = await handle.stat({ bigint: true });
+        if (!sameFileVersion(before, after)) {
+            throw new Error("workspace_candidate_changed_during_scan");
+        }
+        return { sizeBytes, tooLarge: false, sha256, previewText };
     }
     finally {
         await handle.close();
@@ -92,23 +112,18 @@ export async function scanWorkspaceFiles(workspaceDir, limits = {}) {
             const rel = path.relative(workspaceDir, absPath).split(path.sep).join("/");
             if (!isSafeRelativePath(rel))
                 continue;
-            let sizeBytes;
+            let scanned;
             try {
-                const handle = await open(absPath, "r");
-                try {
-                    sizeBytes = (await handle.stat()).size;
-                }
-                finally {
-                    await handle.close();
-                }
+                scanned = await scanStableFile(absPath, maxPreviewChars, maxFileBytes);
             }
             catch {
                 truncated = true;
                 continue;
             }
+            const { sizeBytes } = scanned;
             observedFileCount += 1;
             observedTotalBytes += sizeBytes;
-            if (sizeBytes > maxFileBytes) {
+            if (scanned.tooLarge) {
                 truncated = true;
                 continue;
             }
@@ -116,24 +131,16 @@ export async function scanWorkspaceFiles(workspaceDir, limits = {}) {
                 truncated = true;
                 continue;
             }
-            let sha256;
-            let previewText;
-            try {
-                sha256 = await sha256File(absPath);
-                previewText = await readPreview(absPath, maxPreviewChars);
-            }
-            catch {
-                truncated = true;
-                continue;
-            }
             files.push({
                 absPath,
                 event: "created",
                 path: rel,
                 name: entry.name,
                 size_bytes: sizeBytes,
-                sha256,
-                ...(previewText !== null && previewText !== "" ? { preview_text: previewText } : {}),
+                sha256: scanned.sha256,
+                ...(scanned.previewText !== null && scanned.previewText !== ""
+                    ? { preview_text: scanned.previewText }
+                    : {}),
             });
         }
     }

package/dist/runtime-quiescence.d.ts

@@ -1,16 +1,19 @@
-export interface WorkspaceQuiescenceProof {
-    readonly proofVersion: "workspace-quiescence-proof/1";
+export interface WorkspaceWriterFreezeProof {
+    readonly proofVersion: "workspace-writer-freeze-proof/1";
     readonly sandboxId: string;
     readonly sandboxGeneration: number;
     readonly runtimeSessionId: string;
     readonly checkpointId: string;
-    readonly allWritersStopped: true;
+    readonly allWritersFrozen: true;
 }
+export declare function freezeRuntimeWriters(): Promise<void>;
+export declare function thawRuntimeWriters(): Promise<void>;
+export declare function assertWorkspaceWriterFreezeSupported(): void;
 export declare function quiesceRuntimeWriters(activationId: string | null): Promise<void>;
-export declare function issueWorkspaceQuiescenceProof(scope: {
+export declare function issueWorkspaceWriterFreezeProof(scope: {
     sandboxId: string;
     sandboxGeneration: number;
     runtimeSessionId: string;
     checkpointId: string;
-}): WorkspaceQuiescenceProof;
-export declare function isWorkspaceQuiescenceProof(value: object): value is WorkspaceQuiescenceProof;
+}): WorkspaceWriterFreezeProof;
+export declare function isWorkspaceWriterFreezeProof(value: object): value is WorkspaceWriterFreezeProof;

package/dist/runtime-quiescence.js

@@ -1,8 +1,76 @@
 import { execFile } from "node:child_process";
+import { accessSync, constants as fsConstants } from "node:fs";
+import { readFile, readdir, writeFile } from "node:fs/promises";
+import path from "node:path";
 import { promisify } from "node:util";
 const execFileAsync = promisify(execFile);
 const RUNTIME_LAUNCHER = "/opt/botlearn/bin/botlearn-runtime-launcher";
+const RUNTIME_CGROUP_ROOT = "/sys/fs/cgroup/botlearn-runtime";
 const proofs = new WeakSet();
+const sleep = (milliseconds) => new Promise((resolve) => {
+    setTimeout(resolve, milliseconds);
+});
+async function setDirectCgroupsFrozen(frozen) {
+    let entries;
+    try {
+        entries = await readdir(RUNTIME_CGROUP_ROOT, { withFileTypes: true });
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return;
+        throw error;
+    }
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const directory = path.join(RUNTIME_CGROUP_ROOT, entry.name);
+        await writeFile(path.join(directory, "cgroup.freeze"), frozen ? "1" : "0");
+        for (let attempt = 0; attempt < 100; attempt += 1) {
+            const events = await readFile(path.join(directory, "cgroup.events"), "utf8");
+            if (events.includes(`frozen ${frozen ? 1 : 0}`))
+                break;
+            if (attempt === 99)
+                throw new Error("workspace_runtime_freeze_timeout");
+            await sleep(50);
+        }
+    }
+}
+async function setRuntimeWritersFrozen(frozen) {
+    const mode = process.env.BOTLEARN_RUNTIME_LAUNCH_MODE;
+    if (mode === "direct-uid") {
+        await setDirectCgroupsFrozen(frozen);
+        return;
+    }
+    if (mode === "sudo") {
+        await execFileAsync("/usr/bin/sudo", ["-n", "--", RUNTIME_LAUNCHER, frozen ? "--freeze-all" : "--thaw-all"], { timeout: 10_000 });
+        return;
+    }
+    if (process.env.BOTLEARN_DAEMON_ENABLE_FAKE_RUNTIME === "1" || process.env.NODE_ENV === "test") {
+        return;
+    }
+    throw new Error("workspace_runtime_cgroup_unavailable");
+}
+export async function freezeRuntimeWriters() {
+    await setRuntimeWritersFrozen(true);
+}
+export async function thawRuntimeWriters() {
+    await setRuntimeWritersFrozen(false);
+}
+export function assertWorkspaceWriterFreezeSupported() {
+    const mode = process.env.BOTLEARN_RUNTIME_LAUNCH_MODE;
+    if (mode === "direct-uid") {
+        accessSync(RUNTIME_CGROUP_ROOT, fsConstants.R_OK | fsConstants.W_OK);
+        return;
+    }
+    if (mode === "sudo") {
+        accessSync(RUNTIME_LAUNCHER, fsConstants.X_OK);
+        return;
+    }
+    if (process.env.BOTLEARN_DAEMON_ENABLE_FAKE_RUNTIME === "1" || process.env.NODE_ENV === "test") {
+        return;
+    }
+    throw new Error("workspace_runtime_cgroup_unavailable");
+}
 function managedQuiescenceCommand(activationId) {
     const mode = process.env.BOTLEARN_RUNTIME_LAUNCH_MODE;
     if (mode === "direct-uid") {
@@ -28,15 +96,15 @@ export async function quiesceRuntimeWriters(activationId) {
     }
     await execFileAsync(command[0], command[1], { timeout: 10_000 });
 }
-export function issueWorkspaceQuiescenceProof(scope) {
+export function issueWorkspaceWriterFreezeProof(scope) {
     const proof = Object.freeze({
-        proofVersion: "workspace-quiescence-proof/1",
+        proofVersion: "workspace-writer-freeze-proof/1",
         ...scope,
-        allWritersStopped: true,
+        allWritersFrozen: true,
     });
     proofs.add(proof);
     return proof;
 }
-export function isWorkspaceQuiescenceProof(value) {
+export function isWorkspaceWriterFreezeProof(value) {
     return proofs.has(value);
 }

package/dist/tool-observation.d.ts

@@ -13,12 +13,13 @@ export interface ToolObservationPayload extends Record<string, unknown> {
     redacted: boolean;
 }
 /**
- * Project a provider tool envelope into durable teacher evidence.
+ * Project a provider tool envelope into durable learner-preview and teaching-audit evidence.
  *
  * Only allowlisted operational argument/result fields survive, credentials are removed,
- * and host paths become workspace-relative. `detail_preview` stays a bounded feed-sized
- * excerpt; `detail_full` carries the same allowlisted projection at audit fidelity (deeper
- * walk, larger arrays, 64k chars). Message text, request IDs, and arbitrary envelope
- * metadata never cross this boundary.
+ * and paths inside the current workspace become workspace-relative. Other semantic content,
+ * including execution-host paths outside that workspace, stays intact. `detail_preview` is
+ * a bounded feed-sized excerpt; `detail_full` carries the same allowlisted projection at
+ * audit fidelity (deeper walk, larger arrays, 64k chars). Message text, request IDs, and
+ * arbitrary envelope metadata never cross this boundary.
  */
 export declare function buildToolObservation(block: RuntimeBlock, runtime: string, workspaceDir: string): ToolObservationPayload | null;

package/dist/tool-observation.js

@@ -39,13 +39,14 @@ const RESULT_FIELDS = new Set([
     "bytes",
 ]);
 /**
- * Project a provider tool envelope into durable teacher evidence.
+ * Project a provider tool envelope into durable learner-preview and teaching-audit evidence.
  *
  * Only allowlisted operational argument/result fields survive, credentials are removed,
- * and host paths become workspace-relative. `detail_preview` stays a bounded feed-sized
- * excerpt; `detail_full` carries the same allowlisted projection at audit fidelity (deeper
- * walk, larger arrays, 64k chars). Message text, request IDs, and arbitrary envelope
- * metadata never cross this boundary.
+ * and paths inside the current workspace become workspace-relative. Other semantic content,
+ * including execution-host paths outside that workspace, stays intact. `detail_preview` is
+ * a bounded feed-sized excerpt; `detail_full` carries the same allowlisted projection at
+ * audit fidelity (deeper walk, larger arrays, 64k chars). Message text, request IDs, and
+ * arbitrary envelope metadata never cross this boundary.
  */
 export function buildToolObservation(block, runtime, workspaceDir) {
     if (block.kind !== "tool_call" && block.kind !== "tool_result")

package/dist/trace-projection.d.ts

@@ -17,5 +17,5 @@ export interface ReasoningTracePayload extends Record<string, unknown> {
  * envelope stays local to the sandbox transcript.
  */
 export declare function extractReasoningText(raw: unknown): string;
-/** Project accumulated reasoning text into one durable, redacted, bounded trace payload. */
+/** Project reasoning into one bounded payload that filters credentials and preserves semantics. */
 export declare function buildReasoningTracePayload(text: string, runtime: string, alreadyTruncated?: boolean): ReasoningTracePayload;

package/dist/trace-projection.js

@@ -40,7 +40,7 @@ function collectReasoningStrings(value, depth, out) {
         collectReasoningStrings(item, depth + 1, out);
     }
 }
-/** Project accumulated reasoning text into one durable, redacted, bounded trace payload. */
+/** Project reasoning into one bounded payload that filters credentials and preserves semantics. */
 export function buildReasoningTracePayload(text, runtime, alreadyTruncated = false) {
     const redactedText = redactSecretString(text);
     const truncated = alreadyTruncated || redactedText.length > REASONING_TRACE_MAX_CHARS;

package/dist/workspace-snapshot-control.d.ts

@@ -1,4 +1,4 @@
-import type { WorkspaceQuiescenceProof } from "./runtime-quiescence.js";
+import type { WorkspaceWriterFreezeProof } from "./runtime-quiescence.js";
 interface WorkspaceCheckpointScope {
     checkpointId: string;
     baseRevision: number;
@@ -20,7 +20,7 @@ export declare function checkpointWorkspace(options: {
     reconnectToken: string;
     workspaceDirectory: string;
     scope: WorkspaceCheckpointScope;
-    quiescenceProof: WorkspaceQuiescenceProof;
+    freezeProof: WorkspaceWriterFreezeProof;
 }): Promise<{
     revision: number;
     snapshotId: string | null;

package/dist/workspace-snapshot-control.js

@@ -77,7 +77,7 @@ export async function checkpointWorkspace(options) {
         checkpointId: scope.checkpointId,
         limits: WORKSPACE_SNAPSHOT_POLICY_V1.limits,
         maxStabilityRetries: WORKSPACE_SNAPSHOT_POLICY_V1.maxStabilityRetries,
-        quiescenceProof: options.quiescenceProof,
+        freezeProof: options.freezeProof,
     });
     try {
         const entrySet = {

package/dist/workspace-snapshot-staging.d.ts

@@ -1,4 +1,4 @@
-import { type WorkspaceQuiescenceProof } from "./runtime-quiescence.js";
+import { type WorkspaceWriterFreezeProof } from "./runtime-quiescence.js";
 import { type CanonicalWorkspaceEntrySet, type WorkspaceEntrySetLimits } from "./workspace-entry-set.js";
 export declare class WorkspaceSnapshotStagingError extends Error {
     readonly code: string;
@@ -22,6 +22,6 @@ export interface WorkspaceSnapshotStagingOptions {
     checkpointId: string;
     limits: WorkspaceEntrySetLimits;
     maxStabilityRetries: number;
-    quiescenceProof: WorkspaceQuiescenceProof;
+    freezeProof: WorkspaceWriterFreezeProof;
 }
 export declare function stageWorkspaceSnapshot(options: WorkspaceSnapshotStagingOptions): StagedWorkspaceSnapshot;

package/dist/workspace-snapshot-staging.js

@@ -1,7 +1,7 @@
 import { createHash, randomUUID } from "node:crypto";
 import { chmodSync, closeSync, constants, existsSync, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readdirSync, readSync, realpathSync, rmSync, writeSync, } from "node:fs";
 import path from "node:path";
-import { isWorkspaceQuiescenceProof, } from "./runtime-quiescence.js";
+import { isWorkspaceWriterFreezeProof, } from "./runtime-quiescence.js";
 import { defaultCaseFold, validateWorkspaceEntrySet, WORKSPACE_ENTRY_SET_SCHEMA, } from "./workspace-entry-set.js";
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 const EXCLUDED_NAMES = new Set(["node_modules"]);
@@ -233,14 +233,14 @@ function stageOnce(options, paths) {
 export function stageWorkspaceSnapshot(options) {
     if (!UUID.test(options.checkpointId))
         fail("workspace_snapshot_checkpoint_invalid");
-    if (!isWorkspaceQuiescenceProof(options.quiescenceProof) ||
-        options.quiescenceProof.proofVersion !== "workspace-quiescence-proof/1" ||
-        !UUID.test(options.quiescenceProof.sandboxId) ||
-        !UUID.test(options.quiescenceProof.runtimeSessionId) ||
-        options.quiescenceProof.checkpointId !== options.checkpointId ||
-        !Number.isSafeInteger(options.quiescenceProof.sandboxGeneration) ||
-        options.quiescenceProof.sandboxGeneration < 1 ||
-        options.quiescenceProof.allWritersStopped !== true)
+    if (!isWorkspaceWriterFreezeProof(options.freezeProof) ||
+        options.freezeProof.proofVersion !== "workspace-writer-freeze-proof/1" ||
+        !UUID.test(options.freezeProof.sandboxId) ||
+        !UUID.test(options.freezeProof.runtimeSessionId) ||
+        options.freezeProof.checkpointId !== options.checkpointId ||
+        !Number.isSafeInteger(options.freezeProof.sandboxGeneration) ||
+        options.freezeProof.sandboxGeneration < 1 ||
+        options.freezeProof.allWritersFrozen !== true)
         fail("workspace_snapshot_writer_isolation_unproven");
     if (!Number.isSafeInteger(options.maxStabilityRetries) || options.maxStabilityRetries < 0) {
         fail("workspace_snapshot_retry_limit_invalid");

package/package.json

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