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

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.2";
-export const AGENT_SERVICE_WS_SUBPROTOCOL = "botlearn-agent-sandbox.v2";
+export const AGENT_SERVICE_WS_SCHEMA = "botlearn-agent-sandbox-ws/0.3";
+export const AGENT_SERVICE_WS_SUBPROTOCOL = "botlearn-agent-sandbox.v3";
 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;
@@ -18,6 +18,7 @@ const FRAME_TYPES = new Set([
     "event.ack",
     "auth.rotate",
     "workspace.file.read",
+    "workspace.checkpoint",
     "ping",
     "sandbox.ready",
     "sandbox.heartbeat",
@@ -42,6 +43,7 @@ const SESSION_TYPES = new Set([
     "session.open_failed",
     "session.closed",
     "workspace.file.read",
+    "workspace.checkpoint",
     "workspace.file.result",
 ]);
 /** TURN 帧：必须带 runtime_session_id + agent_run_id + worker_attempt + activation_id 四元组。 */

package/dist/cli.js

@@ -372,7 +372,25 @@ async function cmdAgentServiceSession(args) {
         deepseekTuiVersion: process.env.BOTLEARN_MANAGED_DEEPSEEK_TUI_VERSION?.trim() || undefined,
     });
     clearAgentServiceControlEnv();
-    await client.run();
+    let stopping = false;
+    const stop = () => {
+        if (stopping)
+            return;
+        stopping = true;
+        void client.stopGracefully().catch((error) => {
+            console.error(error instanceof Error ? error.message : "sandbox shutdown failed");
+            client.stop();
+        });
+    };
+    process.once("SIGTERM", stop);
+    process.once("SIGINT", stop);
+    try {
+        await client.run();
+    }
+    finally {
+        process.removeListener("SIGTERM", stop);
+        process.removeListener("SIGINT", stop);
+    }
     return 0;
 }
 // ---------------------------------------------------------------

package/dist/index.d.ts

@@ -14,6 +14,8 @@ export * from "./workspace.js";
 export * from "./workspace-entry-set.js";
 export * from "./workspace-materialization.js";
 export * from "./workspace-snapshot-staging.js";
+export * from "./workspace-snapshot-policy.js";
+export * from "./workspace-snapshot-control.js";
 export * from "./workspace-restore.js";
 export * from "./transcript.js";
 export * from "./file-candidates.js";

package/dist/index.js

@@ -14,6 +14,8 @@ export * from "./workspace.js";
 export * from "./workspace-entry-set.js";
 export * from "./workspace-materialization.js";
 export * from "./workspace-snapshot-staging.js";
+export * from "./workspace-snapshot-policy.js";
+export * from "./workspace-snapshot-control.js";
 export * from "./workspace-restore.js";
 export * from "./transcript.js";
 export * from "./file-candidates.js";

package/dist/run-dispatcher.d.ts

@@ -23,7 +23,7 @@ export interface PreparedPersistentTurn {
 export interface PersistentSessionExecution {
     prepareTurn(payload: RunStartPayload): PreparedPersistentTurn;
     persistNativeSession(sessionId: string): void;
-    finishTurn(payload: RunStartPayload): void;
+    finishTurn(payload: RunStartPayload): Promise<void>;
 }
 export interface RunReportingClient {
     postEvent(agentRunId: string, event: RunEvent): Promise<void | RunEventReceipt>;

package/dist/run-dispatcher.js

@@ -979,7 +979,7 @@ export class RunDispatcher {
                 });
             }
             try {
-                this.persistentSession?.finishTurn(payload);
+                await this.persistentSession?.finishTurn(payload);
             }
             finally {
                 this.inflight.delete(runId);

package/dist/runtime-env.js

@@ -42,11 +42,15 @@ export function clearAgentServiceControlEnv(env = process.env) {
 export function runtimeChildEnv(env = process.env) {
     const childEnv = { ...env };
     const runtimeHome = childEnv.BOTLEARN_RUNTIME_HOME;
+    const activationId = childEnv.BOTLEARN_AGENT_SERVICE_ACTIVATION_ID;
     clearAgentServiceControlEnv(childEnv);
     for (const key of AGENT_SERVICE_SUPERVISOR_ENV_KEYS)
         delete childEnv[key];
     if (runtimeHome)
         childEnv.HOME = runtimeHome;
+    if (activationId && /^[A-Za-z0-9_-]{1,120}$/u.test(activationId)) {
+        childEnv.BOTLEARN_RUNTIME_ACTIVATION_SCOPE = activationId;
+    }
     return childEnv;
 }
 /**
@@ -146,10 +150,6 @@ export function runtimeChildLaunch(binary, args, env = process.env, options = {}
             "-n",
             "-H",
             "-E",
-            "-u",
-            runtimeUser,
-            "-g",
-            runtimeGroup,
             "--",
             MANAGED_RUNTIME_LAUNCHER,
             binary,

package/dist/runtime-quiescence.d.ts

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

package/dist/runtime-quiescence.js

@@ -0,0 +1,42 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+const RUNTIME_LAUNCHER = "/opt/botlearn/bin/botlearn-runtime-launcher";
+const proofs = new WeakSet();
+function managedQuiescenceCommand(activationId) {
+    const mode = process.env.BOTLEARN_RUNTIME_LAUNCH_MODE;
+    if (mode === "direct-uid") {
+        return [RUNTIME_LAUNCHER, [activationId ? "--quiesce" : "--quiesce-all", ...(activationId ? [activationId] : [])]];
+    }
+    if (mode === "sudo") {
+        return [
+            "/usr/bin/sudo",
+            ["-n", "--", RUNTIME_LAUNCHER, activationId ? "--quiesce" : "--quiesce-all", ...(activationId ? [activationId] : [])],
+        ];
+    }
+    return null;
+}
+export async function quiesceRuntimeWriters(activationId) {
+    const command = managedQuiescenceCommand(activationId);
+    if (command === null) {
+        // Local/BYOA runtimes execute as the daemon user and are not eligible for the managed
+        // durable capability. Unit/e2e fake runtimes have no descendant writer to reap.
+        if (process.env.BOTLEARN_DAEMON_ENABLE_FAKE_RUNTIME === "1" || process.env.NODE_ENV === "test") {
+            return;
+        }
+        throw new Error("workspace_runtime_cgroup_unavailable");
+    }
+    await execFileAsync(command[0], command[1], { timeout: 10_000 });
+}
+export function issueWorkspaceQuiescenceProof(scope) {
+    const proof = Object.freeze({
+        proofVersion: "workspace-quiescence-proof/1",
+        ...scope,
+        allWritersStopped: true,
+    });
+    proofs.add(proof);
+    return proof;
+}
+export function isWorkspaceQuiescenceProof(value) {
+    return proofs.has(value);
+}

package/dist/workspace-quota.d.ts

@@ -0,0 +1,4 @@
+export declare const RUNTIME_WORKSPACE_QUOTA_BYTES: number;
+export declare const RUNTIME_WORKSPACE_INODE_QUOTA = 2000;
+export declare function assertRuntimeWorkspaceQuota(workspaceRoot: string): void;
+export declare function applyRuntimeWorkspaceQuota(runtimeSessionId: string, sandboxGeneration: number): Promise<void>;

package/dist/workspace-quota.js

@@ -0,0 +1,42 @@
+import { execFile } from "node:child_process";
+import { readFileSync, statfsSync, statSync } from "node:fs";
+import { promisify } from "node:util";
+export const RUNTIME_WORKSPACE_QUOTA_BYTES = 512 * 1024 * 1024;
+export const RUNTIME_WORKSPACE_INODE_QUOTA = 2_000;
+const WORKSPACE_BACKING_BYTES = 3 * 1024 * 1024 * 1024;
+const QUOTA_MARKER = "/var/lib/botlearn-runtime/workspace-quota.ready";
+const RUNTIME_LAUNCHER = "/opt/botlearn/bin/botlearn-runtime-launcher";
+const execFileAsync = promisify(execFile);
+export function assertRuntimeWorkspaceQuota(workspaceRoot) {
+    if (process.env.BOTLEARN_DAEMON_ENABLE_FAKE_RUNTIME === "1" || process.env.NODE_ENV === "test") {
+        return;
+    }
+    if (process.env.BOTLEARN_RUNTIME_WORKSPACE_QUOTA_BYTES !== String(RUNTIME_WORKSPACE_QUOTA_BYTES) ||
+        process.env.BOTLEARN_RUNTIME_WORKSPACE_INODE_QUOTA !== String(RUNTIME_WORKSPACE_INODE_QUOTA)) {
+        throw new Error("workspace_runtime_quota_unverified");
+    }
+    const filesystem = statfsSync(workspaceRoot, { bigint: true });
+    const marker = statSync(QUOTA_MARKER);
+    if (filesystem.blocks * filesystem.bsize < BigInt(WORKSPACE_BACKING_BYTES) ||
+        marker.uid !== 0 || (marker.mode & 0o777) !== 0o600 ||
+        readFileSync(QUOTA_MARKER, "utf8") !== "workspace-filesystem-quota/1\n") {
+        throw new Error("workspace_runtime_quota_probe_failed");
+    }
+}
+export async function applyRuntimeWorkspaceQuota(runtimeSessionId, sandboxGeneration) {
+    if (process.env.BOTLEARN_DAEMON_ENABLE_FAKE_RUNTIME === "1" || process.env.NODE_ENV === "test") {
+        return;
+    }
+    const args = ["--workspace-quota-apply", runtimeSessionId, String(sandboxGeneration)];
+    if (process.env.BOTLEARN_RUNTIME_LAUNCH_MODE === "sudo") {
+        await execFileAsync("/usr/bin/sudo", ["-n", "--", RUNTIME_LAUNCHER, ...args], {
+            timeout: 10_000,
+        });
+        return;
+    }
+    if (process.env.BOTLEARN_RUNTIME_LAUNCH_MODE === "direct-uid") {
+        await execFileAsync(RUNTIME_LAUNCHER, args, { timeout: 10_000 });
+        return;
+    }
+    throw new Error("workspace_runtime_quota_helper_unavailable");
+}

package/dist/workspace-restore.d.ts

@@ -1,7 +1,8 @@
 import { type WorkspaceEntry, type WorkspaceEntrySetLimits } from "./workspace-entry-set.js";
 export declare class WorkspaceRestoreError extends Error {
     readonly code: string;
-    constructor(code: string);
+    readonly retryable: boolean;
+    constructor(code: string, retryable?: boolean);
 }
 export interface WorkspaceRestoreDescriptor {
     sandboxId: string;
@@ -25,6 +26,12 @@ export interface WorkspaceRestoreOptions {
     requiredFreeBytes: number;
     downloadFile(entry: WorkspaceEntry, partPath: string): Promise<void>;
 }
+export interface WorkspaceRestoreCapacityOptions {
+    workspaceDirectory: string;
+    descriptor: WorkspaceRestoreDescriptor;
+    requiredFreeBytes: number;
+    entryCopies?: 1 | 2;
+}
 export declare function workspaceRestoreJournalPath(controlDirectory: string, runtimeSessionId: string): string;
 export declare function recoverWorkspaceRestoreSwap(options: {
     workspaceDirectory: string;
@@ -32,3 +39,4 @@ export declare function recoverWorkspaceRestoreSwap(options: {
     descriptor: WorkspaceRestoreDescriptor;
 }): boolean;
 export declare function restoreWorkspaceSnapshot(options: WorkspaceRestoreOptions): Promise<void>;
+export declare function assertWorkspaceRestoreCapacity(options: WorkspaceRestoreCapacityOptions): void;

package/dist/workspace-restore.js

@@ -9,14 +9,18 @@ const RESTORE_JOURNAL_SCHEMA = "agent-workspace-restore-journal/1";
 const COPY_CHUNK_BYTES = 64 * 1024;
 export class WorkspaceRestoreError extends Error {
     code;
-    constructor(code) {
+    retryable;
+    constructor(code, retryable = false) {
         super(code);
         this.code = code;
+        this.retryable = retryable;
         this.name = "WorkspaceRestoreError";
     }
 }
 function fail(code) {
-    throw new WorkspaceRestoreError(code);
+    throw new WorkspaceRestoreError(code, code === "workspace_restore_unavailable" ||
+        code === "workspace_restore_disk_pressure" ||
+        code === "workspace_restore_inode_pressure");
 }
 function assertUuid(value, label) {
     if (!UUID.test(value))
@@ -229,9 +233,7 @@ export async function restoreWorkspaceSnapshot(options) {
     const descriptor = options.descriptor;
     assertDescriptor(descriptor);
     assertControlPath(options.workspaceDirectory, options.controlDirectory);
-    if (!Number.isSafeInteger(options.requiredFreeBytes) ||
-        options.requiredFreeBytes < descriptor.expectedTotalBytes)
-        fail("workspace_restore_reservation_invalid");
+    assertWorkspaceRestoreCapacity(options);
     recoverWorkspaceRestoreSwap({
         workspaceDirectory: options.workspaceDirectory,
         controlDirectory: options.controlDirectory,
@@ -244,17 +246,6 @@ export async function restoreWorkspaceSnapshot(options) {
         (descriptor.revision > 0 && canonical.contentSha256 !== descriptor.contentSha256))
         fail("workspace_restore_integrity_failed");
     const parent = path.dirname(options.workspaceDirectory);
-    mkdirSync(parent, { recursive: true, mode: 0o700 });
-    if (existsSync(options.workspaceDirectory)) {
-        const current = lstatSync(options.workspaceDirectory, { bigint: true });
-        if (!current.isDirectory() || current.isSymbolicLink()) {
-            fail("workspace_restore_existing_workspace_invalid");
-        }
-    }
-    const filesystem = statfsSync(parent, { bigint: true });
-    if (filesystem.bavail * filesystem.bsize < BigInt(options.requiredFreeBytes)) {
-        fail("workspace_restore_disk_pressure");
-    }
     const nonce = randomUUID();
     const stagingName = `.botlearn-restore-${descriptor.runtimeSessionId}-${nonce}`;
     const backupName = `.botlearn-backup-${descriptor.runtimeSessionId}-${nonce}`;
@@ -331,3 +322,26 @@ export async function restoreWorkspaceSnapshot(options) {
         throw error;
     }
 }
+export function assertWorkspaceRestoreCapacity(options) {
+    const { descriptor } = options;
+    assertDescriptor(descriptor);
+    if (!Number.isSafeInteger(options.requiredFreeBytes) ||
+        options.requiredFreeBytes < descriptor.expectedTotalBytes)
+        fail("workspace_restore_reservation_invalid");
+    const parent = path.dirname(options.workspaceDirectory);
+    mkdirSync(parent, { recursive: true, mode: 0o700 });
+    if (existsSync(options.workspaceDirectory)) {
+        const current = lstatSync(options.workspaceDirectory, { bigint: true });
+        if (!current.isDirectory() || current.isSymbolicLink()) {
+            fail("workspace_restore_existing_workspace_invalid");
+        }
+    }
+    const filesystem = statfsSync(parent, { bigint: true });
+    if (filesystem.bavail * filesystem.bsize < BigInt(options.requiredFreeBytes)) {
+        fail("workspace_restore_disk_pressure");
+    }
+    const entryCopies = options.entryCopies ?? 1;
+    if (filesystem.ffree < BigInt(descriptor.expectedEntryCount * entryCopies + 16)) {
+        fail("workspace_restore_inode_pressure");
+    }
+}

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

@@ -0,0 +1,29 @@
+import type { WorkspaceQuiescenceProof } from "./runtime-quiescence.js";
+interface WorkspaceCheckpointScope {
+    checkpointId: string;
+    baseRevision: number;
+    sandboxId: string;
+    sandboxGeneration: number;
+    connectionEpoch: number;
+    runtimeSessionId: string;
+    agentRunId?: string;
+    workerAttempt?: number;
+    activationId?: string;
+}
+export declare class WorkspaceSnapshotControlError extends Error {
+    readonly code: string;
+    readonly retryable: boolean;
+    constructor(code: string, retryable: boolean);
+}
+export declare function checkpointWorkspace(options: {
+    wsUrl: string;
+    reconnectToken: string;
+    workspaceDirectory: string;
+    scope: WorkspaceCheckpointScope;
+    quiescenceProof: WorkspaceQuiescenceProof;
+}): Promise<{
+    revision: number;
+    snapshotId: string | null;
+    contentSha256: string;
+}>;
+export {};

package/dist/workspace-snapshot-control.js

@@ -0,0 +1,169 @@
+import { createReadStream, rmSync } from "node:fs";
+import path from "node:path";
+import { ensureDaemonHome } from "./auth-store.js";
+import { writeWorkspaceMaterializationMarker } from "./workspace-materialization.js";
+import { WORKSPACE_SNAPSHOT_POLICY_V1 } from "./workspace-snapshot-policy.js";
+import { stageWorkspaceSnapshot } from "./workspace-snapshot-staging.js";
+export class WorkspaceSnapshotControlError extends Error {
+    code;
+    retryable;
+    constructor(code, retryable) {
+        super(code);
+        this.code = code;
+        this.retryable = retryable;
+        this.name = "WorkspaceSnapshotControlError";
+    }
+}
+function controlBase(wsUrl) {
+    const url = new URL(wsUrl);
+    url.protocol = url.protocol === "wss:" ? "https:" : "http:";
+    url.pathname = "/internal/v1/workspace-checkpoints";
+    url.search = "";
+    url.hash = "";
+    return url.toString().replace(/\/$/, "");
+}
+async function requestJson(url, token, body, signal) {
+    const response = await fetch(url, {
+        method: "POST",
+        headers: {
+            Authorization: `Bearer ${token}`,
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify(body),
+        signal,
+    });
+    if (!response.ok) {
+        let code = `workspace_snapshot_control_${response.status}`;
+        let explicitRetryable;
+        try {
+            const payload = await response.json();
+            const detail = payload.detail;
+            if (detail && typeof detail === "object" && !Array.isArray(detail)) {
+                const stable = detail.code;
+                if (typeof stable === "string" && /^workspace_[a-z0-9_]+$/u.test(stable))
+                    code = stable;
+                const retryable = detail.retryable;
+                if (typeof retryable === "boolean")
+                    explicitRetryable = retryable;
+            }
+        }
+        catch {
+            // Content-free HTTP fallback remains stable and retry classification stays status-based.
+        }
+        throw new WorkspaceSnapshotControlError(code, explicitRetryable ?? (response.status >= 500 || response.status === 408 || response.status === 429 ||
+            response.status === 409));
+    }
+    return await response.json();
+}
+function fence(scope) {
+    return {
+        sandbox_id: scope.sandboxId,
+        sandbox_generation: scope.sandboxGeneration,
+        connection_epoch: scope.connectionEpoch,
+        runtime_session_id: scope.runtimeSessionId,
+        ...(scope.agentRunId ? { agent_run_id: scope.agentRunId } : {}),
+        ...(scope.workerAttempt ? { worker_attempt: scope.workerAttempt } : {}),
+        ...(scope.activationId ? { activation_id: scope.activationId } : {}),
+    };
+}
+export async function checkpointWorkspace(options) {
+    const { scope } = options;
+    const signal = AbortSignal.timeout(WORKSPACE_SNAPSHOT_POLICY_V1.checkpointAttemptDeadlineMs);
+    const checkpointUrl = `${controlBase(options.wsUrl)}/${scope.checkpointId}`;
+    const controlDirectory = path.join(ensureDaemonHome(), "agent-service-sandboxes", scope.sandboxId, "workspace-control");
+    const staged = stageWorkspaceSnapshot({
+        workspaceDirectory: options.workspaceDirectory,
+        controlDirectory,
+        checkpointId: scope.checkpointId,
+        limits: WORKSPACE_SNAPSHOT_POLICY_V1.limits,
+        maxStabilityRetries: WORKSPACE_SNAPSHOT_POLICY_V1.maxStabilityRetries,
+        quiescenceProof: options.quiescenceProof,
+    });
+    try {
+        const entrySet = {
+            schemaVersion: "agent-workspace-entry-set/1",
+            entries: staged.entrySet.entries,
+        };
+        const proposal = await requestJson(`${checkpointUrl}/proposal`, options.reconnectToken, {
+            fence: fence(scope),
+            policy_id: WORKSPACE_SNAPSHOT_POLICY_V1.policyId,
+            base_revision: scope.baseRevision,
+            entry_count: staged.entrySet.entries.length,
+            file_count: staged.entrySet.fileCount,
+            total_bytes: staged.entrySet.totalBytes,
+            content_sha256: staged.entrySet.contentSha256,
+            entry_set: entrySet,
+        }, signal);
+        if (proposal.unchanged) {
+            if (proposal.revision === 0 && proposal.snapshot_id === null) {
+                writeWorkspaceMaterializationMarker({
+                    schemaVersion: "agent-workspace-materialization/1",
+                    sandboxId: scope.sandboxId,
+                    sandboxGeneration: scope.sandboxGeneration,
+                    runtimeSessionId: scope.runtimeSessionId,
+                    workspaceContinuityState: "healthy",
+                    snapshotId: null,
+                    revision: 0,
+                    contentSha256: null,
+                    writtenAt: new Date().toISOString(),
+                });
+            }
+            return {
+                revision: proposal.revision,
+                snapshotId: proposal.snapshot_id,
+                contentSha256: proposal.content_sha256,
+            };
+        }
+        for (let offset = 0; offset < proposal.missing_blob_ids.length; offset += 25) {
+            const requestedBlobIds = proposal.missing_blob_ids.slice(offset, offset + 25);
+            const grants = await requestJson(`${checkpointUrl}/upload-grants`, options.reconnectToken, { fence: fence(scope), blob_ids: requestedBlobIds }, signal);
+            if (grants.length !== requestedBlobIds.length) {
+                throw new Error("workspace_snapshot_upload_grant_count_mismatch");
+            }
+            for (const item of grants) {
+                const source = staged.files.find((file) => file.sha256 === item.sha256 && file.sizeBytes === item.size_bytes);
+                if (!source)
+                    throw new Error("workspace_snapshot_upload_source_missing");
+                const response = await fetch(item.grant.url, {
+                    method: item.grant.method,
+                    headers: item.grant.headers,
+                    body: createReadStream(source.stagingPath),
+                    duplex: "half",
+                    signal,
+                });
+                if (!response.ok)
+                    throw new Error(`workspace_snapshot_upload_${response.status}`);
+            }
+        }
+        let committed = await requestJson(`${checkpointUrl}/complete`, options.reconnectToken, { fence: fence(scope), policy_id: WORKSPACE_SNAPSHOT_POLICY_V1.policyId }, signal);
+        while (committed.status === "pending") {
+            await new Promise((resolve) => setTimeout(resolve, 500));
+            committed = await requestJson(`${checkpointUrl}/status`, options.reconnectToken, { fence: fence(scope) }, signal);
+        }
+        if (committed.status !== "committed" ||
+            committed.snapshot_id === null ||
+            committed.revision === null ||
+            committed.content_sha256 === null) {
+            throw new WorkspaceSnapshotControlError(committed.error_code || "workspace_snapshot_verification_failed", false);
+        }
+        writeWorkspaceMaterializationMarker({
+            schemaVersion: "agent-workspace-materialization/1",
+            sandboxId: scope.sandboxId,
+            sandboxGeneration: scope.sandboxGeneration,
+            runtimeSessionId: scope.runtimeSessionId,
+            workspaceContinuityState: "healthy",
+            snapshotId: committed.snapshot_id,
+            revision: committed.revision,
+            contentSha256: committed.content_sha256,
+            writtenAt: new Date().toISOString(),
+        });
+        return {
+            revision: committed.revision,
+            snapshotId: committed.snapshot_id,
+            contentSha256: committed.content_sha256,
+        };
+    }
+    finally {
+        rmSync(staged.stagingDirectory, { recursive: true, force: true });
+    }
+}

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

@@ -0,0 +1,24 @@
+/**
+ * Protocol limits frozen with Course Service's WorkspaceSnapshotPolicyV1.
+ * Deployment may enable the capability, but must never override these values.
+ */
+export declare const WORKSPACE_SNAPSHOT_POLICY_V1: {
+    readonly policyId: "WorkspaceSnapshotPolicyV1";
+    readonly limits: {
+        maxPathSegmentBytes: number;
+        maxPathBytes: number;
+        maxDepth: number;
+        maxFileBytes: number;
+        maxFileCount: number;
+        maxTotalBytes: number;
+        maxEntrySetBytes: number;
+    };
+    readonly maxStabilityRetries: 2;
+    readonly checkpointAttemptDeadlineMs: 30000;
+    readonly requiredRestoreFreeBytes: number;
+    readonly sessionRetainedHardLimitBytes: number;
+    readonly checkpointReservationBytes: number;
+    readonly restorePageEntries: 25;
+};
+/** Wire representation validated exactly by Agent Service during the v0.3 handshake. */
+export declare function workspaceSnapshotPolicyCapability(): Record<string, unknown>;

package/dist/workspace-snapshot-policy.js

@@ -0,0 +1,45 @@
+import { RUNTIME_WORKSPACE_INODE_QUOTA, RUNTIME_WORKSPACE_QUOTA_BYTES, } from "./workspace-quota.js";
+/**
+ * Protocol limits frozen with Course Service's WorkspaceSnapshotPolicyV1.
+ * Deployment may enable the capability, but must never override these values.
+ */
+export const WORKSPACE_SNAPSHOT_POLICY_V1 = {
+    policyId: "WorkspaceSnapshotPolicyV1",
+    limits: {
+        maxPathSegmentBytes: 255,
+        maxPathBytes: 1024,
+        maxDepth: 32,
+        maxFileBytes: 50 * 1024 * 1024,
+        maxFileCount: 2_000,
+        maxTotalBytes: 512 * 1024 * 1024,
+        maxEntrySetBytes: 1024 * 1024,
+    },
+    maxStabilityRetries: 2,
+    checkpointAttemptDeadlineMs: 30_000,
+    requiredRestoreFreeBytes: 1024 * 1024,
+    sessionRetainedHardLimitBytes: 2 * 1024 * 1024 * 1024,
+    checkpointReservationBytes: 512 * 1024 * 1024,
+    restorePageEntries: 25,
+};
+/** Wire representation validated exactly by Agent Service during the v0.3 handshake. */
+export function workspaceSnapshotPolicyCapability() {
+    return {
+        policy_id: WORKSPACE_SNAPSHOT_POLICY_V1.policyId,
+        max_path_segment_bytes: WORKSPACE_SNAPSHOT_POLICY_V1.limits.maxPathSegmentBytes,
+        max_path_bytes: WORKSPACE_SNAPSHOT_POLICY_V1.limits.maxPathBytes,
+        max_depth: WORKSPACE_SNAPSHOT_POLICY_V1.limits.maxDepth,
+        max_file_bytes: WORKSPACE_SNAPSHOT_POLICY_V1.limits.maxFileBytes,
+        max_file_count: WORKSPACE_SNAPSHOT_POLICY_V1.limits.maxFileCount,
+        max_total_bytes: WORKSPACE_SNAPSHOT_POLICY_V1.limits.maxTotalBytes,
+        max_entry_set_bytes: WORKSPACE_SNAPSHOT_POLICY_V1.limits.maxEntrySetBytes,
+        required_restore_free_bytes: WORKSPACE_SNAPSHOT_POLICY_V1.requiredRestoreFreeBytes,
+        session_retained_hard_limit_bytes: WORKSPACE_SNAPSHOT_POLICY_V1.sessionRetainedHardLimitBytes,
+        checkpoint_reservation_bytes: WORKSPACE_SNAPSHOT_POLICY_V1.checkpointReservationBytes,
+        restore_page_entries: WORKSPACE_SNAPSHOT_POLICY_V1.restorePageEntries,
+        max_stability_retries: WORKSPACE_SNAPSHOT_POLICY_V1.maxStabilityRetries,
+        checkpoint_attempt_deadline_ms: WORKSPACE_SNAPSHOT_POLICY_V1.checkpointAttemptDeadlineMs,
+        prepare_deadline_seconds: 15 * 60,
+        runtime_filesystem_quota_bytes: RUNTIME_WORKSPACE_QUOTA_BYTES,
+        runtime_inode_quota: RUNTIME_WORKSPACE_INODE_QUOTA,
+    };
+}

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

@@ -1,3 +1,4 @@
+import { type WorkspaceQuiescenceProof } from "./runtime-quiescence.js";
 import { type CanonicalWorkspaceEntrySet, type WorkspaceEntrySetLimits } from "./workspace-entry-set.js";
 export declare class WorkspaceSnapshotStagingError extends Error {
     readonly code: string;
@@ -23,12 +24,4 @@ export interface WorkspaceSnapshotStagingOptions {
     maxStabilityRetries: number;
     quiescenceProof: WorkspaceQuiescenceProof;
 }
-export interface WorkspaceQuiescenceProof {
-    proofVersion: "workspace-quiescence-proof/1";
-    sandboxId: string;
-    sandboxGeneration: number;
-    runtimeSessionId: string;
-    checkpointId: string;
-    allWritersStopped: true;
-}
 export declare function stageWorkspaceSnapshot(options: WorkspaceSnapshotStagingOptions): StagedWorkspaceSnapshot;